Full-stack engineer building web apps and exploring Rust and the Solana ecosystem. Zola 2026-12-01T00:00:00+00:00 https://akash11.com/atom.xml 2026-05-10T00:00:00+00:00 2026-05-10T00:00:00+00:00 Unknown https://akash11.com/projects/zola-portfolio/ <h2 id="overview">Overview</h2> <p>A fast, static personal portfolio and blog built with Zola and the Terminus dark theme. Compiles to pure HTML/CSS with no JavaScript framework overhead.</p> <h2 id="features">Features</h2> <ul> <li>Terminal-aesthetic dark theme with monospace typography</li> <li>Blog with pagination and tag taxonomy</li> <li>Paginated projects section with per-project pages</li> <li>Deployed on Vercel with zero config</li> </ul> 2026-03-22T00:00:00+00:00 2026-03-22T00:00:00+00:00 Unknown https://akash11.com/projects/rust-cli-tool/ <h2 id="overview">Overview</h2> <p>A lightweight terminal task manager that stores tasks in a local JSON file. No account, no internet, no Electron — just a single binary that fits into any terminal workflow.</p> <h2 id="features">Features</h2> <ul> <li>Add, complete, delete, and filter tasks</li> <li>Persistent local JSON storage</li> <li>Coloured output for task states</li> <li>Single compiled binary, no runtime dependencies</li> </ul> 2025-12-06T00:00:00+00:00 2025-05-28T00:00:00+00:00 Akash Vaghela https://akash11.com/blog/signature-malleability-from-dirty-bits-in-solidity-types/ <p>Solidity stores all values in 32-byte slots. A <code>uint8</code> only needs 1 byte. The other 31 bytes are unused, and they can hold any data the caller puts there.</p> <p>For most operations, this does not matter. Solidity masks the unused bits automatically, so your function logic sees clean values. But if your contract hashes <code>msg.data</code> directly (to build a unique transaction ID or verify a signature), those extra bits become part of the hash. Two calls with identical logical parameters but different dirty bits will produce different hashes.</p> <p>This is the dirty higher-order bits vulnerability. It allows an attacker to replay a transaction your contract believes it has already seen.</p> <hr /> <h2 id="how-solidity-pads-smaller-types">How Solidity Pads Smaller Types</h2> <p>Every EVM word is 32 bytes (256 bits). When you pass a <code>uint8</code> to a function, the EVM encodes it in a 32-byte slot. The value goes in the rightmost 8 bits. The remaining 248 bits are the "higher-order" bits, and they can be anything.</p> <p>Here is a simple example:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="padding.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> transfer</span><span>(</span><span style="color: #E5C07B;">uint8</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>)</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #7F848E;font-style: italic;"> // Solidity reads only the lowest 8 bits of the input.</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span><span style="color: #7F848E;font-style: italic;"> // The upper 248 bits in msg.data are ignored here.</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">4</span><span>}</span></span></code></pre> <p>These two raw inputs both call <code>transfer(1)</code>:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="plain"><span class="giallo-l"><span>// Clean input: upper bits are zero</span></span> <span class="giallo-l"><span>0x0000000000000000000000000000000000000000000000000000000000000001</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>// Dirty input: upper bits contain arbitrary data</span></span> <span class="giallo-l"><span>0xff00000000000000000000000000000000000000000000000000000000000001</span></span></code></pre> <p>Inside the function body, <code>amount</code> equals <code>1</code> in both cases. Solidity masks off the extra bits before your code runs. The problem is that <code>msg.data</code> gives you the raw, unmasked bytes.</p> <hr /> <h2 id="where-the-vulnerability-appears">Where the Vulnerability Appears</h2> <p>The issue only matters when your contract hashes <code>msg.data</code>, for example to track whether a transaction has already been executed.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="vulnerable.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> VulnerableContract</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;"> mapping</span><span>(</span><span style="color: #E5C07B;">bytes32</span><span> =&gt;</span><span style="color: #E5C07B;"> bool</span><span>)</span><span style="color: #C678DD;"> public</span><span> executed;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> executeOnce</span><span>(</span><span style="color: #E5C07B;">uint8</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>)</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #7F848E;font-style: italic;"> // keccak256(msg.data) includes the dirty upper bits.</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #7F848E;font-style: italic;"> // Two calls with the same `amount` but different padding</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #7F848E;font-style: italic;"> // will produce different hashes.</span></span> <span class="giallo-l" style="background-color: #2C313C;"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #E5C07B;"> bytes32</span><span> txHash </span><span style="color: #56B6C2;">= keccak256</span><span>(</span><span style="color: #E5C07B;">msg</span><span>.data);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #C678DD;"> require</span><span>(!executed[txHash],</span><span style="color: #98C379;"> &quot;Already executed&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span> executed[txHash]</span><span style="color: #56B6C2;"> =</span><span style="color: #D19A66;"> true</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span style="color: #7F848E;font-style: italic;"> // ... do something with amount</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span>}</span></span></code></pre> <p>An attacker can call <code>executeOnce(1)</code> twice: once with clean data and once with dirty data. Each call produces a different <code>txHash</code>. The <code>require</code> passes both times. The replay protection is broken.</p> <p>The attacker does not need any special access. Any caller can craft dirty <code>msg.data</code> by constructing the raw transaction manually.</p> <hr /> <h2 id="which-types-are-affected">Which Types Are Affected</h2> <p>Any Solidity type smaller than 32 bytes can carry dirty bits.</p> <table><thead><tr><th>Type group</th><th>Examples</th><th>Bytes used</th><th>Bits exposed</th></tr></thead><tbody> <tr><td>Unsigned integers</td><td><code>uint8</code> to <code>uint248</code></td><td>1-31</td><td>248 down to 8</td></tr> <tr><td>Signed integers</td><td><code>int8</code> to <code>int248</code></td><td>1-31</td><td>248 down to 8</td></tr> <tr><td>Boolean</td><td><code>bool</code></td><td>1 (stored as <code>uint8</code>)</td><td>248</td></tr> <tr><td>Fixed bytes</td><td><code>bytes1</code> to <code>bytes31</code></td><td>1-31</td><td>248 down to 8</td></tr> <tr><td>Address</td><td><code>address</code></td><td>20</td><td>96</td></tr> <tr><td>Enum</td><td>depends on value count</td><td>usually 1</td><td>usually 248</td></tr> </tbody></table> <p>Types that fill the full 32 bytes have no unused space:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="plain"><span class="giallo-l"><span>uint256, int256, bytes32 =&gt; no dirty bits possible</span></span></code></pre> <blockquote class="markdown-alert-warning"> <p><code>address</code> is 20 bytes, leaving 12 bytes (96 bits) unused. Contracts that hash <code>msg.data</code> containing an address parameter are also vulnerable.</p> </blockquote> <hr /> <h2 id="how-to-fix-it">How to Fix It</h2> <h3 id="hash-the-parameters-directly-not-msg-data">Hash the Parameters Directly, Not <code>msg.data</code></h3> <p>The cleanest fix is to never hash <code>msg.data</code>. Hash the decoded, cleaned parameters instead. Solidity cleans the parameters when it decodes them, so <code>abi.encode(amount)</code> will always produce the same bytes for the same logical value, regardless of what the caller put in the upper bits.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="safe.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> SafeContract</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;"> mapping</span><span>(</span><span style="color: #E5C07B;">bytes32</span><span> =&gt;</span><span style="color: #E5C07B;"> bool</span><span>)</span><span style="color: #C678DD;"> public</span><span> executed;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> executeOnce</span><span>(</span><span style="color: #E5C07B;">uint8</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>)</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #7F848E;font-style: italic;"> // abi.encode uses the cleaned, decoded value.</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #7F848E;font-style: italic;"> // Dirty bits in msg.data have no effect here.</span></span> <span class="giallo-l" style="background-color: #2C313C;"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #E5C07B;"> bytes32</span><span> paramHash </span><span style="color: #56B6C2;">= keccak256</span><span>(</span><span style="color: #E5C07B;">abi</span><span>.</span><span style="color: #61AFEF;">encode</span><span>(amount));</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #C678DD;"> require</span><span>(!executed[paramHash],</span><span style="color: #98C379;"> &quot;Already executed&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span> executed[paramHash]</span><span style="color: #56B6C2;"> =</span><span style="color: #D19A66;"> true</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span style="color: #7F848E;font-style: italic;"> // ... do something with amount</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span>}</span></span></code></pre> <p><code>abi.encode</code> pads values to 32 bytes in a canonical way. Two calls with the same logical <code>amount</code> will always produce the same <code>paramHash</code>.</p> <p>If your function takes multiple parameters, encode them all together:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #E5C07B;">bytes32</span><span> paramHash </span><span style="color: #56B6C2;">= keccak256</span><span>(</span><span style="color: #E5C07B;">abi</span><span>.</span><span style="color: #61AFEF;">encode</span><span>(amount, recipient, nonce));</span></span></code></pre> <p>Do not use <code>abi.encodePacked</code> here. It removes padding, which can create a different kind of collision when types of different sizes are concatenated.</p> <h3 id="use-uint256-when-smaller-types-are-not-necessary">Use <code>uint256</code> When Smaller Types Are Not Necessary</h3> <p>Gas savings from <code>uint8</code> over <code>uint256</code> are often minimal. The EVM operates on 32-byte words anyway. If the smaller type is not required by your data model, use the full-width type.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #7F848E;font-style: italic;">// uint256 leaves no room for dirty bits, so the hash</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #7F848E;font-style: italic;">// of msg.data is always canonical for this parameter.</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> transfer</span><span>(</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>)</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">4</span><span style="color: #E5C07B;"> bytes32</span><span> txHash </span><span style="color: #56B6C2;">= keccak256</span><span>(</span><span style="color: #E5C07B;">msg</span><span>.data);</span><span style="color: #7F848E;font-style: italic;"> // safe with uint256</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">5</span><span>}</span></span></code></pre> <p>This only helps if every parameter in the function is a full 32-byte type. One <code>uint8</code> or <code>address</code> in the signature is enough to reintroduce the problem.</p> <h3 id="validate-input-to-reject-dirty-calls">Validate Input to Reject Dirty Calls</h3> <p>If you must use a smaller type and cannot switch to <code>abi.encode</code>, you can reject calls that contain dirty bits with explicit validation:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="validate.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> strictTransfer</span><span>(</span><span style="color: #E5C07B;">uint8</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>)</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #7F848E;font-style: italic;"> // Reject any input where the upper bits are not zero.</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #7F848E;font-style: italic;"> // This forces callers to submit clean data.</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;"> require</span><span>(</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #E5C07B;"> msg</span><span>.data.length &gt;</span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> 4</span><span> &amp;&amp;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #E5C07B;"> uint256</span><span>(</span><span style="color: #E5C07B;">bytes32</span><span>(</span><span style="color: #E5C07B;">msg</span><span>.data[</span><span style="color: #D19A66;">4</span><span>:])) ==</span><span style="color: #E5C07B;"> uint256</span><span>(amount),</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #98C379;"> &quot;Dirty input rejected&quot;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span> );</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #7F848E;font-style: italic;"> // proceed safely</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span>}</span></span></code></pre> <p>This approach is more fragile and harder to maintain. The <code>abi.encode</code> fix is simpler and correct by construction.</p> <hr /> <h2 id="recommended-practice">Recommended Practice</h2> <p>Always hash cleaned, decoded parameters. Never hash raw <code>msg.data</code>.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span style="color: #7F848E;font-style: italic;">// Correct</span></span> <span class="giallo-l"><span style="color: #E5C07B;">bytes32</span><span> id </span><span style="color: #56B6C2;">= keccak256</span><span>(</span><span style="color: #E5C07B;">abi</span><span>.</span><span style="color: #61AFEF;">encode</span><span>(param1, param2));</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #7F848E;font-style: italic;">// Vulnerable</span></span> <span class="giallo-l"><span style="color: #E5C07B;">bytes32</span><span> id </span><span style="color: #56B6C2;">= keccak256</span><span>(</span><span style="color: #E5C07B;">msg</span><span>.data);</span></span></code></pre> <p>If your contract tracks executed transactions, generates identifiers from function inputs, or builds any hash from <code>msg.data</code>, audit those call sites. Check the types involved. If any parameter is smaller than 32 bytes, you may have this vulnerability.</p> <p>The EVM will not protect you here. The caller controls <code>msg.data</code>, and Solidity only cleans inputs for your function body, not before the bytes hit <code>msg.data</code>.</p> 2025-12-01T00:00:00+00:00 2026-12-01T00:00:00+00:00 Unknown https://akash11.com/projects/expense-tracker/ <h2 id="overview">Overview</h2> <p>A production-ready REST API for tracking personal expenses, assigning categories, and generating monthly summaries. Built API-first so it can connect to any frontend or automation script.</p> <h2 id="features">Features</h2> <ul> <li>JWT authentication</li> <li>Expense CRUD with category tagging</li> <li>Monthly and category breakdown report endpoints</li> <li>Dockerised for one-command local dev</li> <li>OpenAPI docs auto-generated by FastAPI</li> </ul> <h2 id="screenshots">Screenshots</h2> <p><img src="/images/s1.png" alt="image1" /> <img src="/images/s2.png" alt="image1" /> <img src="/images/s3.png" alt="image1" /></p> <h2 id="demo">Demo</h2> <iframe src="https://www.youtube.com/embed/dQw4w9WgXcQ" frameborder="0" allowfullscreen style="width:100%;aspect-ratio:16/9;display:block;"> </iframe> <p>you can download from here if you want</p> <a href="&#x2F;files&#x2F;resume.pdf" download class="download-btn"> <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"> <path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" /> <polyline points="7 10 12 15 17 10" /> <line x1="12" y1="15" x2="12" y2="3" /> </svg> resume.pdf <span class="download-size">142 KB</span> </a> 2025-11-22T00:00:00+00:00 2025-11-22T00:00:00+00:00 Akash Vaghela https://akash11.com/blog/erc-2981-how-nft-royalties-work-at-the-contract-level/ <p>Before ERC-2981, NFT royalties were a handshake agreement between creators and marketplaces. Each platform did things differently. Most did nothing. A creator could mint a collection, watch it trade for millions in secondary sales, and receive nothing past the initial mint.</p> <p>ERC-2981 is a standard interface that gives any NFT contract a way to report royalty information: who gets paid, and how much, for a given sale price. Marketplaces that support the standard query this information and route payments correctly.</p> <p>This post explains how the standard works, how to implement it in Solidity using OpenZeppelin, and what its real limitations are.</p> <h2 id="the-interface">The Interface</h2> <p>The entire standard is built around one function:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="IERC2981.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">interface</span><span style="color: #E5C07B;"> IERC2981</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> royaltyInfo</span><span>(</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> tokenId</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> salePrice</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span> )</span><span style="color: #C678DD;"> external view returns</span><span> (</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #E5C07B;"> address</span><span style="color: #E06C75;font-style: italic;"> receiver</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> royaltyAmount</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span> );</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span>}</span></span></code></pre> <p>When a supported marketplace processes a sale, it calls <code>royaltyInfo()</code> with the token ID and the sale price in wei. The contract returns two values: the address that should receive the royalty, and the amount in wei.</p> <p>That's the full interface. The standard does not define how royalties are stored, calculated, or updated. That's left to the implementation.</p> <h2 id="royalties-in-basis-points">Royalties in Basis Points</h2> <p>Royalty percentages in ERC-2981 are expressed in basis points. One basis point equals 0.01%, so 10,000 basis points equals 100%.</p> <table><thead><tr><th>Percentage</th><th>Basis Points</th></tr></thead><tbody> <tr><td>1%</td><td>100</td></tr> <tr><td>2.5%</td><td>250</td></tr> <tr><td>5%</td><td>500</td></tr> <tr><td>7.5%</td><td>750</td></tr> <tr><td>10%</td><td>1000</td></tr> </tbody></table> <p>The calculation used to convert a sale price to a royalty amount is:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="plain"><span class="giallo-l"><span>royaltyAmount = (salePrice * feeBasisPoints) / 10000</span></span></code></pre> <p>For a 2 ETH sale at 5%:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="plain"><span class="giallo-l"><span>royaltyAmount = (2_000_000_000_000_000_000 * 500) / 10000</span></span> <span class="giallo-l"><span>royaltyAmount = 100_000_000_000_000_000 wei = 0.1 ETH</span></span></code></pre> <p>Basis points avoid floating point entirely, which Solidity does not support.</p> <h2 id="a-basic-implementation-with-openzeppelin">A Basic Implementation with OpenZeppelin</h2> <p>OpenZeppelin provides an <code>ERC2981</code> base contract that handles the storage and calculation logic. You inherit it alongside <code>ERC721</code> and override <code>supportsInterface()</code> to declare both:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="MyNFT.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #7F848E;font-style: italic;">// SPDX-License-Identifier: MIT</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;">pragma</span><span style="color: #E06C75;"> solidity</span><span style="color: #D19A66;"> ^0.8.20</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;">import</span><span style="color: #98C379;"> &quot;@openzeppelin/contracts/token/ERC721/ERC721.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #C678DD;">import</span><span style="color: #98C379;"> &quot;@openzeppelin/contracts/token/common/ERC2981.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> MyNFT</span><span style="color: #C678DD;"> is</span><span style="color: #E5C07B;"> ERC721</span><span>, </span><span style="color: #E5C07B;">ERC2981</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #C678DD;"> constructor</span><span>()</span><span style="color: #61AFEF;"> ERC721</span><span>(&quot;MyNFT&quot;, &quot;MNFT&quot;) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #7F848E;font-style: italic;"> // 5% royalty to the deployer for all tokens</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #61AFEF;"> _setDefaultRoyalty</span><span>(</span><span style="color: #E5C07B;">msg.sender</span><span>,</span><span style="color: #D19A66;"> 500</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span style="color: #7F848E;font-style: italic;"> // Required when inheriting multiple contracts that implement supportsInterface</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> supportsInterface</span><span>(</span><span style="color: #E5C07B;">bytes4</span><span style="color: #E06C75;font-style: italic;"> interfaceId</span><span>)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span style="color: #C678DD;"> public</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span style="color: #C678DD;"> view</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">17</span><span style="color: #C678DD;"> virtual</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">18</span><span style="color: #C678DD;"> override</span><span>(</span><span style="color: #61AFEF;">ERC721</span><span>,</span><span style="color: #61AFEF;"> ERC2981</span><span>)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">19</span><span style="color: #C678DD;"> returns</span><span> (</span><span style="color: #E5C07B;">bool</span><span>)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">20</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">21</span><span style="color: #C678DD;"> return</span><span style="color: #E5C07B;font-style: italic;"> super</span><span>.</span><span style="color: #61AFEF;">supportsInterface</span><span>(interfaceId);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">22</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">23</span><span>}</span></span></code></pre> <p>The <code>_setDefaultRoyalty()</code> call sets a royalty that applies to every token in the collection unless overridden.</p> <h2 id="default-royalties-vs-per-token-royalties">Default Royalties vs Per-Token Royalties</h2> <p>ERC-2981 supports two royalty models. You can use either or both in the same contract.</p> <p><strong>Default royalty</strong> applies to every token that does not have its own royalty set:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #61AFEF;">_setDefaultRoyalty</span><span>(creatorAddress,</span><span style="color: #D19A66;"> 750</span><span>);</span><span style="color: #7F848E;font-style: italic;"> // 7.5% for all tokens</span></span></code></pre> <p><strong>Per-token royalty</strong> overrides the default for a specific token:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #61AFEF;">_setTokenRoyalty</span><span>(tokenId, specificCreator,</span><span style="color: #D19A66;"> 1000</span><span>);</span><span style="color: #7F848E;font-style: italic;"> // 10% for this token only</span></span></code></pre> <p>Per-token royalties are useful for collaborative collections where different artists contribute individual pieces and each should receive royalties from their own work.</p> <h2 id="a-complete-example-mintable-collection-with-updatable-royalties">A Complete Example: Mintable Collection with Updatable Royalties</h2> <p>Here is a more realistic contract. Each token sets its royalty to the minting address at mint time. The token owner can update the royalty later.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="ArtCollection.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #7F848E;font-style: italic;">// SPDX-License-Identifier: MIT</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;">pragma</span><span style="color: #E06C75;"> solidity</span><span style="color: #D19A66;"> ^0.8.20</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;">import</span><span style="color: #98C379;"> &quot;@openzeppelin/contracts/token/ERC721/ERC721.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #C678DD;">import</span><span style="color: #98C379;"> &quot;@openzeppelin/contracts/token/common/ERC2981.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> ArtCollection</span><span style="color: #C678DD;"> is</span><span style="color: #E5C07B;"> ERC721</span><span>, </span><span style="color: #E5C07B;">ERC2981</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #E5C07B;"> uint256</span><span style="color: #C678DD;"> private</span><span> _nextTokenId;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #C678DD;"> constructor</span><span>()</span><span style="color: #61AFEF;"> ERC721</span><span>(&quot;Art Collection&quot;, &quot;ART&quot;) {}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> mint</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> to</span><span>)</span><span style="color: #C678DD;"> public returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span style="color: #E5C07B;"> uint256</span><span> tokenId </span><span style="color: #56B6C2;">= ++</span><span>_nextTokenId;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span style="color: #61AFEF;"> _safeMint</span><span>(to, tokenId);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span style="color: #7F848E;font-style: italic;"> // 2.5% royalty going to the minting address</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">17</span><span style="color: #61AFEF;"> _setTokenRoyalty</span><span>(tokenId, to,</span><span style="color: #D19A66;"> 250</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">18</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">19</span><span style="color: #C678DD;"> return</span><span> tokenId;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">20</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">21</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">22</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> updateRoyalty</span><span>(</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">23</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> tokenId</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">24</span><span style="color: #E5C07B;"> address</span><span style="color: #E06C75;font-style: italic;"> receiver</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">25</span><span style="color: #E5C07B;"> uint96</span><span style="color: #E06C75;font-style: italic;"> feeNumerator</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">26</span><span> )</span><span style="color: #C678DD;"> external</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">27</span><span style="color: #C678DD;"> require</span><span>(</span><span style="color: #61AFEF;">ownerOf</span><span>(tokenId) ==</span><span style="color: #E5C07B;"> msg.sender</span><span>,</span><span style="color: #98C379;"> &quot;Not token owner&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">28</span><span style="color: #61AFEF;"> _setTokenRoyalty</span><span>(tokenId, receiver, feeNumerator);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">29</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">30</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">31</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> supportsInterface</span><span>(</span><span style="color: #E5C07B;">bytes4</span><span style="color: #E06C75;font-style: italic;"> interfaceId</span><span>)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">32</span><span style="color: #C678DD;"> public</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">33</span><span style="color: #C678DD;"> view</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">34</span><span style="color: #C678DD;"> override</span><span>(</span><span style="color: #61AFEF;">ERC721</span><span>,</span><span style="color: #61AFEF;"> ERC2981</span><span>)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">35</span><span style="color: #C678DD;"> returns</span><span> (</span><span style="color: #E5C07B;">bool</span><span>)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">36</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">37</span><span style="color: #C678DD;"> return</span><span style="color: #E5C07B;font-style: italic;"> super</span><span>.</span><span style="color: #61AFEF;">supportsInterface</span><span>(interfaceId);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">38</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">39</span><span>}</span></span></code></pre> <blockquote class="markdown-alert-note"> <p>Allowing token owners to update royalties is a design choice with real tradeoffs. It gives flexibility but also lets someone change where royalties go after a token is sold. Consider whether that fits your use case before including <code>updateRoyalty()</code>.</p> </blockquote> <h2 id="how-marketplaces-check-for-support">How Marketplaces Check for Support</h2> <p>Before calling <code>royaltyInfo()</code>, a marketplace should verify the contract declares ERC-2981 support through ERC-165:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #E5C07B;">bytes4</span><span style="color: #C678DD;"> private constant</span><span> _INTERFACE_ID_ERC2981 </span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> 0x2a55205a</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> supportsRoyalties</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> nftContract</span><span>)</span><span style="color: #C678DD;"> public view returns</span><span> (</span><span style="color: #E5C07B;">bool</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;"> try</span><span style="color: #61AFEF;"> IERC165</span><span>(nftContract).</span><span style="color: #61AFEF;">supportsInterface</span><span>(_INTERFACE_ID_ERC2981)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #C678DD;"> returns</span><span> (</span><span style="color: #E5C07B;">bool</span><span style="color: #E06C75;font-style: italic;"> supported</span><span>)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #C678DD;"> return</span><span> supported;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span> }</span><span style="color: #C678DD;"> catch</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #C678DD;"> return</span><span style="color: #D19A66;"> false</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span>}</span></span></code></pre> <p>The interface ID <code>0x2a55205a</code> is derived from the <code>royaltyInfo()</code> function selector. It is fixed by the standard.</p> <p>Since <code>royaltyInfo()</code> is a <code>view</code> function, calling it costs no gas. Marketplaces can query royalty data off-chain when building a transaction, then include the royalty transfer in the sale transaction itself.</p> <h2 id="what-erc-2981-cannot-do">What ERC-2981 Cannot Do</h2> <p>The standard has three limitations worth understanding before you rely on it.</p> <p><strong>Royalties are not enforced.</strong> A marketplace can call <code>royaltyInfo()</code> and then ignore the result. The standard provides information, not enforcement. There is no mechanism in the standard itself to block a transfer on a non-compliant platform.</p> <p>OpenSea attempted to address this in 2022 with the Operator Filter Registry, which let creators block transfers through contracts that did not honor royalties. The approach had mixed results and generated significant debate about creator rights versus open market access. It remains an unsolved problem at the protocol level.</p> <p><strong>Only one recipient per token.</strong> <code>royaltyInfo()</code> returns a single <code>address</code>. If you want royalties split among multiple collaborators, you need a separate payment splitter contract that acts as the recipient and redistributes funds internally:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="PaymentSplitter.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> RoyaltySplitter</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #E5C07B;"> address</span><span>[]</span><span style="color: #C678DD;"> public</span><span> payees;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #E5C07B;"> uint256</span><span>[]</span><span style="color: #C678DD;"> public</span><span> shares;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #C678DD;"> constructor</span><span>(</span><span style="color: #E5C07B;">address</span><span>[]</span><span style="color: #C678DD;"> memory</span><span style="font-style: italic;"> _payees</span><span>,</span><span style="color: #E5C07B;"> uint256</span><span>[]</span><span style="color: #C678DD;"> memory</span><span style="font-style: italic;"> _shares</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #7F848E;font-style: italic;"> // store payees and their share ratios</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #61AFEF;"> receive</span><span>()</span><span style="color: #C678DD;"> external payable</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #7F848E;font-style: italic;"> // distribute incoming ETH proportionally</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span>}</span></span></code></pre> <p>You would deploy this splitter, then set its address as the royalty receiver in your NFT contract.</p> <p><strong>Marketplace adoption is not guaranteed.</strong> Major platforms like OpenSea, Rarible, and LooksRare support ERC-2981. Smaller exchanges, aggregators, and peer-to-peer tools may not. If someone trades your NFT through a non-supporting venue, the royalty is not paid and nothing in the standard can stop that.</p> <h2 id="when-to-use-erc-2981">When to Use ERC-2981</h2> <p>ERC-2981 is the right choice when:</p> <ul> <li>You are building a new NFT collection and want royalty support on major marketplaces</li> <li>Different tokens in your collection should have different royalty rates or recipients</li> <li>You want a standard that existing tooling already understands</li> </ul> <p>It is not a complete solution when on-chain royalty enforcement is a hard requirement. For that, you need transfer restrictions at the token level, which come with their own tradeoffs around composability and user experience.</p> <h2 id="summary">Summary</h2> <p>ERC-2981 solves a specific, narrow problem: it gives NFT contracts a standard way to report royalty information. Any marketplace that queries <code>royaltyInfo()</code> and acts on the result will pay royalties correctly. The standard works well for that purpose.</p> <p>What it does not solve is enforcement. A standard can only define a shared language. Whether platforms respect that language is a social and economic question, not a technical one.</p> 2025-11-22T00:00:00+00:00 2025-11-22T00:00:00+00:00 Akash Vaghela https://akash11.com/blog/erc-4626-tokenized-vault-standard/ <p>ERC-4626 is a Solidity interface standard for yield-bearing vaults. It defines a single, consistent way for protocols to accept deposits, issue shares, and return assets on withdrawal. This post explains how the standard works, why the math behaves the way it does, and what to watch out for when implementing or integrating with it.</p> <h2 id="the-problem-it-solves">The Problem It Solves</h2> <p>Before ERC-4626, every yield protocol built its own vault interface. Yearn issued <code>yTokens</code>. Compound issued <code>cTokens</code>. Aave issued <code>aTokens</code>. Each worked differently at the function level.</p> <p>This meant every integration required custom code. An aggregator that wanted to support five yield protocols had to write five different adapters. A bug in one adapter did not apply to the others. Auditing was harder. Development was slower.</p> <p>ERC-4626 gives every vault the same function signatures and the same mathematical guarantees. Deposit tokens, receive shares. Redeem shares, receive tokens. An aggregator written against ERC-4626 works with any compliant vault without modification.</p> <h2 id="how-shares-and-assets-relate">How Shares and Assets Relate</h2> <p>A vault holds an underlying <code>asset</code> (for example, USDC). When you deposit, you receive <code>shares</code> in return. Shares represent your proportional ownership of everything inside the vault.</p> <p>The relationship between shares and assets is defined by this ratio:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="plain"><span class="giallo-l"><span>exchange rate = totalAssets() / totalSupply()</span></span></code></pre> <p>At launch, a vault typically starts at 1:1. As the vault earns yield and <code>totalAssets()</code> grows, each share becomes redeemable for more of the underlying asset.</p> <p>Here is a concrete example:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="plain"><span class="giallo-l"><span>State: 10,000 USDC in the vault, 8,000 shares outstanding</span></span> <span class="giallo-l"><span>Exchange rate: 10,000 / 8,000 = 1.25 USDC per share</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>You deposit 1,000 USDC:</span></span> <span class="giallo-l"><span>Shares minted = 1,000 / 1.25 = 800 shares</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>Later, the vault earns yield: now 11,000 USDC, 8,800 shares outstanding</span></span> <span class="giallo-l"><span>You redeem your 800 shares:</span></span> <span class="giallo-l"><span>Assets returned = 800 * (11,000 / 8,800) = 1,000 USDC * 1.04... ≈ 1,045 USDC</span></span></code></pre> <p>Your shares became worth more. You did not need to claim anything. The exchange rate carried the yield.</p> <h2 id="the-core-interface">The Core Interface</h2> <p>Every ERC-4626 vault implements these functions:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #7F848E;font-style: italic;">// Returns the address of the underlying token</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> asset</span><span>()</span><span style="color: #C678DD;"> external view returns</span><span> (</span><span style="color: #E5C07B;">address</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #7F848E;font-style: italic;">// Returns total underlying tokens managed by the vault</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> totalAssets</span><span>()</span><span style="color: #C678DD;"> external view returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #7F848E;font-style: italic;">// Deposits `assets` tokens, mints shares to `receiver`</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> deposit</span><span>(</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> assets</span><span>,</span><span style="color: #E5C07B;"> address</span><span style="color: #E06C75;font-style: italic;"> receiver</span><span>)</span><span style="color: #C678DD;"> external returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> shares</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #7F848E;font-style: italic;">// Mints exactly `shares` shares, pulls required assets from caller</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> mint</span><span>(</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> shares</span><span>,</span><span style="color: #E5C07B;"> address</span><span style="color: #E06C75;font-style: italic;"> receiver</span><span>)</span><span style="color: #C678DD;"> external returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> assets</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span style="color: #7F848E;font-style: italic;">// Burns shares from `owner`, sends exactly `assets` tokens to `receiver`</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> withdraw</span><span>(</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> assets</span><span>,</span><span style="color: #E5C07B;"> address</span><span style="color: #E06C75;font-style: italic;"> receiver</span><span>,</span><span style="color: #E5C07B;"> address</span><span style="color: #E06C75;font-style: italic;"> owner</span><span>)</span><span style="color: #C678DD;"> external returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> shares</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span style="color: #7F848E;font-style: italic;">// Burns exactly `shares` from `owner`, sends resulting tokens to `receiver`</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">17</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> redeem</span><span>(</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> shares</span><span>,</span><span style="color: #E5C07B;"> address</span><span style="color: #E06C75;font-style: italic;"> receiver</span><span>,</span><span style="color: #E5C07B;"> address</span><span style="color: #E06C75;font-style: italic;"> owner</span><span>)</span><span style="color: #C678DD;"> external returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> assets</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">18</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">19</span><span style="color: #7F848E;font-style: italic;">// Preview functions (view, no state changes)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">20</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> previewDeposit</span><span>(</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> assets</span><span>)</span><span style="color: #C678DD;"> external view returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> shares</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">21</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> previewMint</span><span>(</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> shares</span><span>)</span><span style="color: #C678DD;"> external view returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> assets</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">22</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> previewWithdraw</span><span>(</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> assets</span><span>)</span><span style="color: #C678DD;"> external view returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> shares</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">23</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> previewRedeem</span><span>(</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> shares</span><span>)</span><span style="color: #C678DD;"> external view returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> assets</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">24</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">25</span><span style="color: #7F848E;font-style: italic;">// Limits</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">26</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> maxDeposit</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> receiver</span><span>)</span><span style="color: #C678DD;"> external view returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">27</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> maxMint</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> receiver</span><span>)</span><span style="color: #C678DD;"> external view returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">28</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> maxWithdraw</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> owner</span><span>)</span><span style="color: #C678DD;"> external view returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">29</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> maxRedeem</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> owner</span><span>)</span><span style="color: #C678DD;"> external view returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>);</span></span></code></pre><h3 id="deposit-vs-mint-withdraw-vs-redeem">Deposit vs Mint, Withdraw vs Redeem</h3> <p>The standard provides two entry paths and two exit paths. The difference is which side you fix.</p> <table><thead><tr><th>Operation</th><th>You fix</th><th>The vault determines</th></tr></thead><tbody> <tr><td><code>deposit</code></td><td>How many assets to put in</td><td>How many shares you receive</td></tr> <tr><td><code>mint</code></td><td>How many shares you want</td><td>How many assets to pull</td></tr> <tr><td><code>withdraw</code></td><td>How many assets to get back</td><td>How many shares to burn</td></tr> <tr><td><code>redeem</code></td><td>How many shares to burn</td><td>How many assets to return</td></tr> </tbody></table> <p>Use <code>deposit</code> and <code>redeem</code> in most cases. Use <code>mint</code> and <code>withdraw</code> when the contract on the other side needs exact amounts, such as when fulfilling a specific share-denominated obligation.</p> <h2 id="a-minimal-implementation">A Minimal Implementation</h2> <p>The simplest compliant vault just holds tokens in place, with no yield strategy at all:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="BasicVault.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #7F848E;font-style: italic;">// SPDX-License-Identifier: MIT</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;">pragma</span><span style="color: #E06C75;"> solidity</span><span style="color: #D19A66;"> ^0.8.20</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;">import</span><span> {</span><span style="color: #E5C07B;">ERC4626</span><span>}</span><span style="color: #C678DD;"> from</span><span style="color: #98C379;"> &quot;@openzeppelin/contracts/token/ERC20/extensions/ERC4626.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #C678DD;">import</span><span> {</span><span style="color: #E5C07B;">ERC20</span><span>}</span><span style="color: #C678DD;"> from</span><span style="color: #98C379;"> &quot;@openzeppelin/contracts/token/ERC20/ERC20.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #C678DD;">import</span><span> {</span><span style="color: #E5C07B;">IERC20</span><span>}</span><span style="color: #C678DD;"> from</span><span style="color: #98C379;"> &quot;@openzeppelin/contracts/token/ERC20/IERC20.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> BasicVault</span><span style="color: #C678DD;"> is</span><span style="color: #E5C07B;"> ERC4626</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #C678DD;"> constructor</span><span>(</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #C678DD;"> IERC20</span><span style="font-style: italic;"> _asset</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span style="color: #E5C07B;"> string</span><span style="color: #C678DD;"> memory</span><span style="font-style: italic;"> _name</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span style="color: #E5C07B;"> string</span><span style="color: #C678DD;"> memory</span><span style="font-style: italic;"> _symbol</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span> )</span><span style="color: #61AFEF;"> ERC4626</span><span>(_asset) </span><span style="color: #61AFEF;">ERC20</span><span>(_name, _symbol) {}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> totalAssets</span><span>()</span><span style="color: #C678DD;"> public view override returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span style="color: #C678DD;"> return</span><span style="color: #61AFEF;"> IERC20</span><span>(</span><span style="color: #61AFEF;">asset</span><span>()).</span><span style="color: #61AFEF;">balanceOf</span><span>(</span><span style="color: #E5C07B;">address</span><span>(</span><span style="color: #E5C07B;">this</span><span>));</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">17</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">18</span><span>}</span></span></code></pre> <p>Real vaults deploy yield strategies inside <code>totalAssets()</code> or through a separate <code>harvest()</code> function that compounds returns and updates the vault's balance.</p> <h2 id="the-inflation-attack">The Inflation Attack</h2> <p>Early vault designs had a known exploit. Here is how it works:</p> <ol> <li>An attacker deposits 1 wei as the first depositor. They receive 1 share.</li> <li>The attacker transfers 1,000,000 tokens directly to the vault contract (not through <code>deposit</code>). This does not mint shares.</li> <li>The exchange rate is now 1,000,001 assets per share.</li> <li>A victim deposits 999,999 tokens. Integer division gives them 0 shares.</li> <li>The victim receives nothing. The attacker redeems their 1 share and takes everything.</li> </ol> <p>Two approaches defend against this.</p> <h3 id="virtual-offset">Virtual Offset</h3> <p>Add a virtual balance and virtual supply to the exchange rate calculation:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="VirtualOffsetVault.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> _convertToShares</span><span>(</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> assets</span><span>,</span><span style="color: #C678DD;"> Math</span><span>.</span><span style="color: #E06C75;">Rounding</span><span style="color: #E06C75;font-style: italic;"> rounding</span><span>)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;"> internal view override returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span>{</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;"> return</span><span> assets.</span><span style="color: #61AFEF;">mulDiv</span><span>(</span></span> <span class="giallo-l" style="background-color: #2C313C;"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #61AFEF;"> totalSupply</span><span>()</span><span style="color: #56B6C2;"> +</span><span style="color: #D19A66;"> 10</span><span style="color: #56B6C2;"> **</span><span style="color: #61AFEF;"> _decimalsOffset</span><span>(),</span><span style="color: #7F848E;font-style: italic;"> // virtual supply offset</span></span> <span class="giallo-l" style="background-color: #2C313C;"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #61AFEF;"> totalAssets</span><span>()</span><span style="color: #56B6C2;"> +</span><span style="color: #D19A66;"> 1</span><span>,</span><span style="color: #7F848E;font-style: italic;"> // virtual asset offset</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span> rounding</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span> );</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span>}</span></span></code></pre> <p>OpenZeppelin's <code>ERC4626</code> implementation uses a <code>_decimalsOffset()</code> hook for exactly this purpose. Setting it to a non-zero value (commonly <code>0</code> for most tokens, higher for tokens with few decimals) adds the offset automatically.</p> <h3 id="dead-shares">Dead Shares</h3> <p>Mint a small number of shares to <code>address(0)</code> in the constructor, permanently locking them:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="DeadSharesVault.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #C678DD;">constructor</span><span>(</span><span style="color: #C678DD;">IERC20</span><span style="font-style: italic;"> _asset</span><span>)</span><span style="color: #61AFEF;"> ERC4626</span><span>(_asset) </span><span style="color: #61AFEF;">ERC20</span><span>(&quot;Vault&quot;, &quot;vTKN&quot;) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #7F848E;font-style: italic;"> // Lock initial liquidity so the exchange rate cannot be manipulated cheaply</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span><span style="color: #61AFEF;"> _mint</span><span>(</span><span style="color: #E5C07B;">address</span><span>(</span><span style="color: #D19A66;">0xdead</span><span>),</span><span style="color: #D19A66;"> 1000</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">4</span><span>}</span></span></code></pre> <p>This raises the cost of the attack significantly. The attacker would need to donate enough to overwhelm the dead shares.</p> <blockquote class="markdown-alert-warning"> <p>If you deploy a vault without inflation protection and someone front-runs the first deposit, the vault can be permanently broken for honest users. Add protection before deployment, not after.</p> </blockquote> <h2 id="fee-structures">Fee Structures</h2> <p>Vaults typically charge fees through share dilution rather than direct asset transfers. A performance fee works like this:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="FeeVault.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> harvest</span><span>()</span><span style="color: #C678DD;"> external</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #E5C07B;"> uint256</span><span> currentAssets </span><span style="color: #56B6C2;">=</span><span style="color: #61AFEF;"> totalAssets</span><span>();</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #E5C07B;"> uint256</span><span> profit </span><span style="color: #56B6C2;">=</span><span> currentAssets </span><span style="color: #56B6C2;">-</span><span> lastRecordedAssets;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #C678DD;"> if</span><span> (profit &gt;</span><span style="color: #D19A66;"> 0</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #E5C07B;"> uint256</span><span> feeInAssets </span><span style="color: #56B6C2;">=</span><span> (profit </span><span style="color: #56B6C2;">*</span><span> performanceFee)</span><span style="color: #56B6C2;"> /</span><span style="color: #D19A66;"> 10_000</span><span>;</span><span style="color: #7F848E;font-style: italic;"> // basis points</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #E5C07B;"> uint256</span><span> feeShares </span><span style="color: #56B6C2;">=</span><span style="color: #61AFEF;"> convertToShares</span><span>(feeInAssets);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #7F848E;font-style: italic;"> // Minting shares to the protocol dilutes all other holders proportionally</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #61AFEF;"> _mint</span><span>(feeRecipient, feeShares);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span> lastRecordedAssets </span><span style="color: #56B6C2;">=</span><span style="color: #61AFEF;"> totalAssets</span><span>();</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span>}</span></span></code></pre> <p>Minting shares to a recipient reduces the share price for everyone else by a small, proportional amount. No asset transfers happen. The fee is implicit in the dilution.</p> <h2 id="integrating-with-erc-4626-vaults">Integrating with ERC-4626 Vaults</h2> <p>Because every ERC-4626 vault exposes the same interface, aggregators and routers can interact with any compliant vault using the same code:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="DeFiAggregator.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">interface</span><span style="color: #E5C07B;"> IERC4626</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> asset</span><span>()</span><span style="color: #C678DD;"> external view returns</span><span> (</span><span style="color: #E5C07B;">address</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> deposit</span><span>(</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> assets</span><span>,</span><span style="color: #E5C07B;"> address</span><span style="color: #E06C75;font-style: italic;"> receiver</span><span>)</span><span style="color: #C678DD;"> external returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> shares</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> redeem</span><span>(</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> shares</span><span>,</span><span style="color: #E5C07B;"> address</span><span style="color: #E06C75;font-style: italic;"> receiver</span><span>,</span><span style="color: #E5C07B;"> address</span><span style="color: #E06C75;font-style: italic;"> owner</span><span>)</span><span style="color: #C678DD;"> external returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> assets</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> previewDeposit</span><span>(</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> assets</span><span>)</span><span style="color: #C678DD;"> external view returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> shares</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> VaultRouter</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> zapIntoVault</span><span>(</span><span style="color: #C678DD;">IERC4626</span><span style="color: #E06C75;font-style: italic;"> vault</span><span>,</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>)</span><span style="color: #C678DD;"> external</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span> IERC20 underlying </span><span style="color: #56B6C2;">=</span><span style="color: #61AFEF;"> IERC20</span><span>(vault.</span><span style="color: #61AFEF;">asset</span><span>());</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span> underlying.</span><span style="color: #61AFEF;">transferFrom</span><span>(</span><span style="color: #E5C07B;">msg.sender</span><span>,</span><span style="color: #E5C07B;"> address</span><span>(</span><span style="color: #E5C07B;">this</span><span>), amount);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span> underlying.</span><span style="color: #61AFEF;">approve</span><span>(</span><span style="color: #E5C07B;">address</span><span>(vault), amount);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span> vault.</span><span style="color: #61AFEF;">deposit</span><span>(amount,</span><span style="color: #E5C07B;"> msg.sender</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span>}</span></span></code></pre> <p>This router works for any vault, whether it is a Yearn strategy, a Beefy compounder, or a custom protocol, as long as the vault implements ERC-4626.</p> <h2 id="real-world-considerations">Real-World Considerations</h2> <h3 id="slippage-protection">Slippage Protection</h3> <p>Always check preview functions before transacting and enforce a minimum output:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #E5C07B;">uint256</span><span> expectedShares </span><span style="color: #56B6C2;">=</span><span> vault.</span><span style="color: #61AFEF;">previewDeposit</span><span>(amount);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #E5C07B;">uint256</span><span> minShares </span><span style="color: #56B6C2;">=</span><span> (expectedShares </span><span style="color: #56B6C2;">*</span><span style="color: #D19A66;"> 99</span><span>)</span><span style="color: #56B6C2;"> /</span><span style="color: #D19A66;"> 100</span><span>;</span><span style="color: #7F848E;font-style: italic;"> // 1% slippage tolerance</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">4</span><span style="color: #E5C07B;">uint256</span><span> actualShares </span><span style="color: #56B6C2;">=</span><span> vault.</span><span style="color: #61AFEF;">deposit</span><span>(amount, receiver);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">5</span><span style="color: #C678DD;">require</span><span>(actualShares &gt;</span><span style="color: #56B6C2;">=</span><span> minShares,</span><span style="color: #98C379;"> &quot;Slippage exceeded&quot;</span><span>);</span></span></code></pre> <p>Some vaults charge entry or exit fees that the preview functions may not fully account for, depending on implementation. Read the vault documentation before assuming previews are exact.</p> <h3 id="deposit-and-withdrawal-limits">Deposit and Withdrawal Limits</h3> <p>Vaults can cap total deposits or impose per-user limits. Always check before transacting:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #E5C07B;">uint256</span><span> depositLimit </span><span style="color: #56B6C2;">=</span><span> vault.</span><span style="color: #61AFEF;">maxDeposit</span><span>(</span><span style="color: #E5C07B;">msg.sender</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #C678DD;">require</span><span>(depositAmount &lt;</span><span style="color: #56B6C2;">=</span><span> depositLimit,</span><span style="color: #98C379;"> &quot;Exceeds vault capacity&quot;</span><span>);</span></span></code></pre><h3 id="withdrawal-delays">Withdrawal Delays</h3> <p>Some yield strategies lock assets in external protocols. The vault may not be able to return funds immediately. <code>maxWithdraw()</code> and <code>maxRedeem()</code> tell you how much is available right now:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #E5C07B;">uint256</span><span> availableNow </span><span style="color: #56B6C2;">=</span><span> vault.</span><span style="color: #61AFEF;">maxWithdraw</span><span>(</span><span style="color: #E5C07B;">msg.sender</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #C678DD;">if</span><span> (desiredAmount &gt; availableNow) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span><span style="color: #7F848E;font-style: italic;"> // Handle partial withdrawal or enter a withdrawal queue</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">4</span><span>}</span></span></code></pre><h3 id="rounding">Rounding</h3> <p>Integer division always truncates. The standard specifies how to round: round in favor of the vault on deposits, round in favor of the user on withdrawals. This prevents users from extracting value through repeated small operations.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #7F848E;font-style: italic;">// Deposit: round shares DOWN (vault-favorable)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span>shares </span><span style="color: #56B6C2;">=</span><span> assets.</span><span style="color: #61AFEF;">mulDiv</span><span>(</span><span style="color: #61AFEF;">totalSupply</span><span>(),</span><span style="color: #61AFEF;"> totalAssets</span><span>(), Math.Rounding.Floor);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">4</span><span style="color: #7F848E;font-style: italic;">// Withdraw: round shares UP (user-favorable, meaning fewer shares burned)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">5</span><span style="color: #7F848E;font-style: italic;">// Redeem: round assets DOWN (user-favorable, meaning fewer assets expected to be exact)</span></span></code></pre> <p>OpenZeppelin's implementation handles this correctly. If you are writing a custom vault, verify your rounding direction matches the spec.</p> <h2 id="security-risks">Security Risks</h2> <p><strong>Reentrancy.</strong> Deposit and withdrawal functions transfer tokens, which can trigger callbacks in ERC-777 or similar token contracts. Use the checks-effects-interactions pattern or a reentrancy guard on all external-facing vault functions.</p> <p><strong>Oracle manipulation.</strong> If <code>totalAssets()</code> reads a price from an AMM or external oracle, a flash loan can manipulate the exchange rate within a single transaction. Use time-weighted average prices or other manipulation-resistant methods if your vault's asset accounting depends on price feeds.</p> <p><strong>Direct token transfers.</strong> Tokens sent to the vault address without calling <code>deposit()</code> increase <code>totalAssets()</code> but do not mint shares. This is a donation that benefits all existing shareholders. It can also be used as part of an inflation attack if the vault is not protected.</p> <h2 id="testing-fundamentals">Testing Fundamentals</h2> <p>Two properties must hold for any correct vault implementation.</p> <p><strong>Round-trip integrity:</strong> depositing and immediately withdrawing should return approximately the same amount, minus only legitimate fees and rounding:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="VaultTest.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> testRoundTrip</span><span>()</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #E5C07B;"> uint256</span><span> depositAmount </span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> 1000e18</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #E5C07B;"> uint256</span><span> shares </span><span style="color: #56B6C2;">=</span><span> vault.</span><span style="color: #61AFEF;">deposit</span><span>(depositAmount, user);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #E5C07B;"> uint256</span><span> assetsBack </span><span style="color: #56B6C2;">=</span><span> vault.</span><span style="color: #61AFEF;">redeem</span><span>(shares, user, user);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #7F848E;font-style: italic;"> // Allow for rounding up to 2 wei</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #61AFEF;"> assertApproxEqAbs</span><span>(assetsBack, depositAmount,</span><span style="color: #D19A66;"> 2</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span>}</span></span></code></pre> <p><strong>Inflation resistance:</strong> a direct token transfer to the vault should not allow an attacker to extract a later depositor's funds:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="VaultTest.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> testInflationAttack</span><span>()</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #7F848E;font-style: italic;"> // Attacker plants a small deposit</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span> vault.</span><span style="color: #61AFEF;">deposit</span><span>(</span><span style="color: #D19A66;">1</span><span>, attacker);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #7F848E;font-style: italic;"> // Attacker donates directly to the vault contract</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span> token.</span><span style="color: #61AFEF;">transfer</span><span>(</span><span style="color: #E5C07B;">address</span><span>(vault),</span><span style="color: #D19A66;"> 1e18</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #7F848E;font-style: italic;"> // Victim deposits a large amount</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #E5C07B;"> uint256</span><span> shares </span><span style="color: #56B6C2;">=</span><span> vault.</span><span style="color: #61AFEF;">deposit</span><span>(</span><span style="color: #D19A66;">1000e18</span><span>, victim);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span style="color: #7F848E;font-style: italic;"> // Victim must receive meaningful shares</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span style="color: #61AFEF;"> assertGt</span><span>(shares,</span><span style="color: #D19A66;"> 0</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span>}</span></span></code></pre> <p>If your vault fails the second test, you need inflation protection before deployment.</p> <h2 id="when-erc-4626-fits-and-when-it-does-not">When ERC-4626 Fits and When It Does Not</h2> <p>The standard works well for:</p> <ul> <li>Yield aggregators that pool user deposits into a single strategy</li> <li>Single-asset staking with auto-compounding returns</li> <li>Lending protocols where depositors earn interest over time</li> <li>Treasury management systems that need a standardized vault interface</li> </ul> <p>It is a poor fit for:</p> <ul> <li>Multi-asset vaults. The standard assumes one underlying <code>asset</code>. Vaults that hold baskets of tokens require a different design.</li> <li>NFT-based strategies. Shares are fungible ERC-20 tokens. You cannot represent fractional or unique positions within the standard.</li> <li>Vaults with complex, conditional withdrawal rules. <code>maxWithdraw()</code> is a simple integer. If withdrawal eligibility depends on time locks, governance votes, or other state, the standard cannot express that fully.</li> </ul> <h2 id="summary">Summary</h2> <p>ERC-4626 standardizes the deposit-share-redeem cycle so that any integrator can work with any compliant vault using the same code. The exchange rate rises as yield accumulates. Preview functions let callers simulate outcomes before transacting. The standard has known risks (inflation attacks, rounding, reentrancy) that have established mitigations.</p> <p>If you are building a new yield vault, start from OpenZeppelin's <code>ERC4626</code> base contract. It handles the exchange rate math, rounding direction, and inflation protection correctly. Add your yield strategy on top.</p> 2025-11-22T00:00:00+00:00 2025-11-22T00:00:00+00:00 Akash Vaghela https://akash11.com/blog/erc-777-the-token-standard-that-tried-to-fix-erc-20/ <p>ERC-777 was proposed in 2017 to fix a specific, well-known problem: ERC-20 tokens had no way to notify a contract when tokens arrived. This caused tokens to get stuck in contracts silently, and it forced developers to use the awkward <code>approve</code> + <code>transferFrom</code> two-step flow. ERC-777 introduced hooks, operators, and a richer send interface to address these problems.</p> <p>This post covers how ERC-777 works, what it adds over ERC-20, where it struggles, and why most projects still avoid it.</p> <h2 id="the-problem-erc-777-solves">The Problem ERC-777 Solves</h2> <p>With ERC-20, if you send tokens directly to a contract using <code>transfer</code>, the contract has no idea the tokens arrived. There is no callback, no notification, no hook. The tokens sit in the contract with no way to trigger any logic.</p> <p>The workaround is the <code>approve</code> + <code>transferFrom</code> pattern. You first call <code>approve</code> to allow the contract to pull tokens, then the contract calls <code>transferFrom</code> to actually take them. Two transactions. Two signatures. Higher gas costs.</p> <p>ERC-777 replaces both of these patterns with a hook system. When tokens arrive at a contract, the standard automatically calls a function on that contract to notify it. This makes token receipt an event the contract can respond to, not something it has to poll or pull.</p> <h2 id="hooks-the-core-innovation">Hooks: The Core Innovation</h2> <p>The key addition in ERC-777 is two hooks: <code>tokensToSend</code> and <code>tokensReceived</code>.</p> <p><code>tokensToSend</code> is optional. It fires before tokens leave the sender's address. A sender contract can implement this to intercept or reject outgoing transfers.</p> <p><code>tokensReceived</code> is mandatory for contract recipients. If a contract receives ERC-777 tokens but does not implement <code>tokensReceived</code>, the transfer reverts. This prevents tokens from being sent to contracts that cannot handle them.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> tokensReceived</span><span>(</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #E5C07B;"> address</span><span style="color: #E06C75;font-style: italic;"> operator</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #E5C07B;"> address</span><span style="color: #E06C75;font-style: italic;"> from</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #E5C07B;"> address</span><span style="color: #E06C75;font-style: italic;"> to</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #E5C07B;"> bytes</span><span style="color: #C678DD;"> calldata</span><span style="color: #E06C75;font-style: italic;"> userData</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #E5C07B;"> bytes</span><span style="color: #C678DD;"> calldata</span><span style="color: #E06C75;font-style: italic;"> operatorData</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span>)</span><span style="color: #C678DD;"> external</span><span>;</span></span></code></pre> <p>The <code>userData</code> and <code>operatorData</code> parameters are also new. They let the sender attach arbitrary bytes to a transfer, similar to a memo on a bank transfer. A receiving contract can parse these bytes to decide what to do with the incoming tokens.</p> <h2 id="operators">Operators</h2> <p>ERC-777 introduces the concept of operators: addresses that are authorized to send tokens on behalf of another address. This is different from ERC-20's <code>approve</code> mechanism.</p> <p>With ERC-20 <code>approve</code>, you authorize a specific spender to spend up to a specific amount. With ERC-777 operators, you authorize an address to move any amount of your tokens until you revoke that authorization.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #7F848E;font-style: italic;">// Authorize an operator</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> authorizeOperator</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> operator</span><span>)</span><span style="color: #C678DD;"> external</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #7F848E;font-style: italic;">// Revoke an operator</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> revokeOperator</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> operator</span><span>)</span><span style="color: #C678DD;"> external</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #7F848E;font-style: italic;">// Check authorization</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> isOperatorFor</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> operator</span><span>,</span><span style="color: #E5C07B;"> address</span><span style="color: #E06C75;font-style: italic;"> tokenHolder</span><span>)</span><span style="color: #C678DD;"> external view returns</span><span> (</span><span style="color: #E5C07B;">bool</span><span>);</span></span></code></pre> <p>There is also a concept of default operators. These are addresses the token creator designates as operators for all token holders at deployment time. They can be used for things like automatic fee collection or protocol-level transfers. Token holders can revoke default operators individually, but they are active by default unless revoked.</p> <h2 id="the-send-interface">The Send Interface</h2> <p>ERC-777 replaces <code>transfer</code> with <code>send</code>:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> send</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> recipient</span><span>,</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>,</span><span style="color: #E5C07B;"> bytes</span><span style="color: #C678DD;"> calldata</span><span style="color: #E06C75;font-style: italic;"> data</span><span>)</span><span style="color: #C678DD;"> external</span><span>;</span></span></code></pre> <p>The <code>data</code> parameter is the memo. Any contract or wallet can pass arbitrary bytes here, and the recipient contract receives them in <code>tokensReceived</code>. This enables use cases like routing logic inside a vault, attaching order IDs to payments, or passing configuration flags alongside a transfer.</p> <h2 id="how-a-transfer-actually-flows">How a Transfer Actually Flows</h2> <p>When you call <code>send</code>, the execution follows this sequence:</p> <ol> <li>Check the sender has enough balance.</li> <li>Look up if the sender is a contract. If it is, call <code>tokensToSend</code> on it if the sender has registered an implementation.</li> <li>Deduct the balance from the sender and add it to the recipient.</li> <li>Look up if the recipient is a contract. If it is, call <code>tokensReceived</code> on it. This call is required. If the recipient is a contract and does not implement <code>tokensReceived</code>, the whole transaction reverts.</li> <li>Transfer completes.</li> </ol> <p>The lookup in steps 2 and 4 is done using the ERC-1820 registry, described below.</p> <h2 id="erc-1820-the-interface-registry">ERC-1820: The Interface Registry</h2> <p>ERC-777 depends on ERC-1820, a global registry contract deployed at the same address on every EVM-compatible chain:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="plain"><span class="giallo-l"><span>0x1820a4B7618BdE71Dce8cdc73aAB6C95905faD24</span></span></code></pre> <p>ERC-1820 answers the question: "does this address implement interface X?" Every ERC-777 token registers itself with ERC-1820. Every contract that wants to receive ERC-777 tokens registers its <code>tokensReceived</code> implementation.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #E5C07B;">bytes32</span><span style="color: #C678DD;"> constant</span><span> TOKENS_RECIPIENT_INTERFACE_HASH </span><span style="color: #56B6C2;">=</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #56B6C2;"> keccak256</span><span>(</span><span style="color: #98C379;">&quot;ERC777TokensRecipient&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">4</span><span style="color: #E5C07B;">address</span><span> implementer </span><span style="color: #56B6C2;">=</span><span> erc1820Registry.</span><span style="color: #61AFEF;">getInterfaceImplementer</span><span>(</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">5</span><span> account,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">6</span><span> TOKENS_RECIPIENT_INTERFACE_HASH</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">7</span><span>);</span></span></code></pre> <p>If <code>implementer</code> is the zero address, the recipient has not registered a <code>tokensReceived</code> hook. For a contract recipient, this causes the transfer to revert.</p> <h2 id="backward-compatibility-with-erc-20">Backward Compatibility with ERC-20</h2> <p>ERC-777 tokens implement all ERC-20 functions. Old interfaces, wallets, and contracts that only know about ERC-20 will still work with an ERC-777 token.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #7F848E;font-style: italic;">// These still work on an ERC-777 token</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> transfer</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> recipient</span><span>,</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>)</span><span style="color: #C678DD;"> external returns</span><span> (</span><span style="color: #E5C07B;">bool</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> approve</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> spender</span><span>,</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>)</span><span style="color: #C678DD;"> external returns</span><span> (</span><span style="color: #E5C07B;">bool</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">4</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> transferFrom</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> sender</span><span>,</span><span style="color: #E5C07B;"> address</span><span style="color: #E06C75;font-style: italic;"> recipient</span><span>,</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>)</span><span style="color: #C678DD;"> external returns</span><span> (</span><span style="color: #E5C07B;">bool</span><span>);</span></span></code></pre> <p>The catch: when you use ERC-20 functions on an ERC-777 token, the hooks do not fire. The <code>tokensReceived</code> callback does not execute. This matters if a contract depends on the hook to update state when tokens arrive. If someone sends tokens via the ERC-20 <code>transfer</code> path, the hook is skipped and the contract state may become inconsistent.</p> <h2 id="a-working-receiver-contract">A Working Receiver Contract</h2> <p>Here is a minimal vault contract that correctly receives ERC-777 tokens:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="TokenVault.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #7F848E;font-style: italic;">// SPDX-License-Identifier: MIT</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;">pragma</span><span style="color: #E06C75;"> solidity</span><span style="color: #D19A66;"> ^0.8.0</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;">import</span><span style="color: #98C379;"> &quot;@openzeppelin/contracts/token/ERC777/IERC777.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #C678DD;">import</span><span style="color: #98C379;"> &quot;@openzeppelin/contracts/token/ERC777/IERC777Recipient.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #C678DD;">import</span><span style="color: #98C379;"> &quot;@openzeppelin/contracts/utils/introspection/IERC1820Registry.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> TokenVault</span><span style="color: #C678DD;"> is</span><span style="color: #E5C07B;"> IERC777Recipient</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span> IERC777 </span><span style="color: #C678DD;">public</span><span> token;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span> IERC1820Registry </span><span style="color: #C678DD;">private constant</span><span> _ERC1820_REGISTRY </span><span style="color: #56B6C2;">=</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span style="color: #61AFEF;"> IERC1820Registry</span><span>(</span><span style="color: #D19A66;">0x1820a4B7618BdE71Dce8cdc73aAB6C95905faD24</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span style="color: #E5C07B;"> bytes32</span><span style="color: #C678DD;"> private constant</span><span> _TOKENS_RECIPIENT_INTERFACE_HASH </span><span style="color: #56B6C2;">=</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span style="color: #56B6C2;"> keccak256</span><span>(</span><span style="color: #98C379;">&quot;ERC777TokensRecipient&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">17</span><span style="color: #C678DD;"> constructor</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> tokenAddress</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">18</span><span> token </span><span style="color: #56B6C2;">=</span><span style="color: #61AFEF;"> IERC777</span><span>(tokenAddress);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">19</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">20</span><span style="color: #7F848E;font-style: italic;"> // Register this contract as a tokensReceived implementer</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">21</span><span> _ERC1820_REGISTRY.</span><span style="color: #61AFEF;">setInterfaceImplementer</span><span>(</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">22</span><span style="color: #E5C07B;"> address</span><span>(</span><span style="color: #E5C07B;">this</span><span>),</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">23</span><span> _TOKENS_RECIPIENT_INTERFACE_HASH,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">24</span><span style="color: #E5C07B;"> address</span><span>(</span><span style="color: #E5C07B;">this</span><span>)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">25</span><span> );</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">26</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">27</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">28</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> tokensReceived</span><span>(</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">29</span><span style="color: #E5C07B;"> address</span><span style="color: #E06C75;font-style: italic;"> operator</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">30</span><span style="color: #E5C07B;"> address</span><span style="color: #E06C75;font-style: italic;"> from</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">31</span><span style="color: #E5C07B;"> address</span><span style="color: #E06C75;font-style: italic;"> to</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">32</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">33</span><span style="color: #E5C07B;"> bytes</span><span style="color: #C678DD;"> calldata</span><span style="color: #E06C75;font-style: italic;"> userData</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">34</span><span style="color: #E5C07B;"> bytes</span><span style="color: #C678DD;"> calldata</span><span style="color: #E06C75;font-style: italic;"> operatorData</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">35</span><span> )</span><span style="color: #C678DD;"> external override</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">36</span><span style="color: #C678DD;"> require</span><span>(</span><span style="color: #E5C07B;">msg.sender</span><span> ==</span><span style="color: #E5C07B;"> address</span><span>(token),</span><span style="color: #98C379;"> &quot;Unknown token&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">37</span><span style="color: #7F848E;font-style: italic;"> // Tokens are already credited to this contract at this point.</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">38</span><span style="color: #7F848E;font-style: italic;"> // userData can be parsed here to trigger specific vault logic.</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">39</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">40</span><span>}</span></span></code></pre> <p>Notice that the constructor registers the contract with ERC-1820. Without this registration, any ERC-777 transfer to this address would revert.</p> <h2 id="security-the-reentrancy-problem">Security: The Reentrancy Problem</h2> <p>The hook mechanism introduces a serious reentrancy risk. When <code>send</code> is called, it executes the recipient's <code>tokensReceived</code> function before the transfer fully settles in some implementations. A malicious or buggy recipient can re-enter the calling contract during this callback.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #7F848E;font-style: italic;">// Vulnerable pattern</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> withdraw</span><span>(</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>)</span><span style="color: #C678DD;"> external</span><span> {</span></span> <span class="giallo-l" style="background-color: #2C313C;"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span><span> token.</span><span style="color: #61AFEF;">send</span><span>(</span><span style="color: #E5C07B;">msg.sender</span><span>, amount,</span><span style="color: #98C379;"> &quot;&quot;</span><span>);</span><span style="color: #7F848E;font-style: italic;"> // Calls tokensReceived on msg.sender</span></span> <span class="giallo-l" style="background-color: #2C313C;"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">4</span><span> userBalance[</span><span style="color: #E5C07B;">msg.sender</span><span>]</span><span style="color: #56B6C2;"> -=</span><span> amount;</span><span style="color: #7F848E;font-style: italic;"> // State updated after external call</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">5</span><span>}</span></span></code></pre> <p>On line 3, <code>send</code> triggers <code>tokensReceived</code> on <code>msg.sender</code>. If <code>msg.sender</code> is a malicious contract, it can call <code>withdraw</code> again inside <code>tokensReceived</code> before line 4 executes. The balance check passes each time because <code>userBalance</code> has not been decremented yet.</p> <p>This is not hypothetical. In 2020, several DeFi protocols that used ERC-777 tokens suffered reentrancy attacks exploiting exactly this pattern. The hooks make the attack surface larger than with plain ERC-20.</p> <blockquote class="markdown-alert-warning"> <p>If you work with ERC-777 tokens, always follow the checks-effects-interactions pattern. Update state before making any external call, including <code>send</code>.</p> </blockquote> <p>The hook mechanism also means gas costs are higher and harder to predict. You are executing unknown code in the recipient contract. The gas usage for a transfer depends on what the recipient's hook does.</p> <h2 id="why-erc-777-never-replaced-erc-20">Why ERC-777 Never Replaced ERC-20</h2> <p>The problems ERC-777 solved were real. The hooks are genuinely useful. But the standard came with enough new risks that most developers chose not to adopt it.</p> <p>The reentrancy attacks in 2020 made the tradeoffs concrete. It is not that ERC-777 is insecure by design, but that it makes writing secure contracts harder. Developers need to be aware of the hook execution order, register with ERC-1820, and handle the ERC-20 compatibility gap carefully.</p> <p>Major protocols explicitly rejected ERC-777 over these concerns. Uniswap only supports ERC-20. When a protocol as widely used as Uniswap does not support a standard, that standard will not become the default.</p> <p>ERC-20 also has momentum. Tooling, auditing patterns, wallet support, and developer intuition are all built around ERC-20. Switching to ERC-777 means relearning assumptions that were already settled.</p> <p>Newer standards like ERC-4626 for vault tokens and ERC-1155 for multi-token contracts solve specific problems without inheriting ERC-777's complexity. Projects that need richer token behavior tend to go to one of those instead.</p> <h2 id="when-erc-777-is-worth-considering">When ERC-777 Is Worth Considering</h2> <p>ERC-777 is not useless. It fits specific situations where the hook mechanism provides real value and the team is prepared to handle the security implications.</p> <p>Protocol-level tokens where operators are needed for automated logic are a reasonable fit. Tokens used inside closed systems where every recipient is a known, audited contract are another case where the risks are more contained.</p> <p>If you are building a simple fungible token for general use, stick with ERC-20. If you need vault or yield-bearing token behavior, look at ERC-4626. ERC-777 occupies a narrow space where its specific features are the right tool for the job.</p> <h2 id="summary">Summary</h2> <p>ERC-777 introduced three meaningful improvements over ERC-20: hooks for contract notification, operators for delegated token management, and a richer <code>send</code> interface with attached data. It maintained backward compatibility with ERC-20 to avoid a hard migration.</p> <p>In practice, the reentrancy risks from hooks, the dependency on ERC-1820, the gas unpredictability, and the ERC-20 compatibility gap made adoption slow. Most of the ecosystem stayed on ERC-20, and the specific problems ERC-777 solved were addressed through better patterns and auditing rather than a new standard.</p> <p>The concepts ERC-777 introduced are still worth understanding. Hooks, operator patterns, and attached data are ideas that appear in other standards and protocols. Knowing how ERC-777 implemented them, and where the implementation went wrong, is useful context for working with any token system.</p> 2025-11-21T00:00:00+00:00 2025-11-21T00:00:00+00:00 Akash Vaghela https://akash11.com/blog/erc-1155-the-multi-token-standard-for-ethereum/ <p>Before ERC-1155, building a game with both a currency token and unique item NFTs meant deploying two separate contracts. One ERC-20 for the currency. One ERC-721 for the items. Every additional token type meant another deployment, more gas, and more contracts to maintain.</p> <p>ERC-1155 solves this. One contract manages unlimited token types, handles fungible and non-fungible tokens, and supports batch operations that reduce transaction costs substantially.</p> <p>This post explains how ERC-1155 works, walks through real implementation patterns, and compares it to ERC-20 and ERC-721 so you know when to reach for each.</p> <h2 id="the-core-idea">The Core Idea</h2> <p>ERC-1155 introduces a two-dimensional balance mapping. Where ERC-20 maps <code>address =&gt; uint256</code>, ERC-1155 maps <code>address =&gt; tokenId =&gt; uint256</code>. That extra dimension is everything.</p> <p>Each token type gets an ID. The same ID can represent a fungible token (minted in quantity N) or an NFT (minted in quantity 1). The contract does not distinguish between them at the protocol level. You decide what each ID means.</p> <p>Think of it as a warehouse with numbered bins:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="plain"><span class="giallo-l"><span>Warehouse (ERC-1155 Contract)</span></span> <span class="giallo-l"><span>├── Bin #0: Gold Coins (fungible, quantity: 1,000,000)</span></span> <span class="giallo-l"><span>├── Bin #1: Legendary Sword (NFT, quantity: 1)</span></span> <span class="giallo-l"><span>├── Bin #2: Common Shield (semi-fungible, quantity: 500)</span></span> <span class="giallo-l"><span>└── Bin #3: Rare Potion (semi-fungible, quantity: 50)</span></span></code></pre> <p>One warehouse. One deployment. Any mix of token types.</p> <h2 id="basic-implementation">Basic Implementation</h2> <p>Here is a minimal ERC-1155 contract using OpenZeppelin:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="GameItems.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #7F848E;font-style: italic;">// SPDX-License-Identifier: MIT</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;">pragma</span><span style="color: #E06C75;"> solidity</span><span style="color: #D19A66;"> ^0.8.0</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;">import</span><span style="color: #98C379;"> &quot;@openzeppelin/contracts/token/ERC1155/ERC1155.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> GameItems</span><span style="color: #C678DD;"> is</span><span style="color: #E5C07B;"> ERC1155</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #E5C07B;"> uint256</span><span style="color: #C678DD;"> public constant</span><span> GOLD </span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> 0</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #E5C07B;"> uint256</span><span style="color: #C678DD;"> public constant</span><span> SWORD </span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> 1</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #E5C07B;"> uint256</span><span style="color: #C678DD;"> public constant</span><span> SHIELD </span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> 2</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span style="color: #C678DD;"> constructor</span><span>()</span><span style="color: #61AFEF;"> ERC1155</span><span>(&quot;https://game.example/api/item/{id}.json&quot;) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span style="color: #61AFEF;"> _mint</span><span>(</span><span style="color: #E5C07B;">msg.sender</span><span>, GOLD,</span><span style="color: #D19A66;"> 10000</span><span>,</span><span style="color: #98C379;"> &quot;&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span style="color: #61AFEF;"> _mint</span><span>(</span><span style="color: #E5C07B;">msg.sender</span><span>, SWORD,</span><span style="color: #D19A66;"> 1</span><span>,</span><span style="color: #98C379;"> &quot;&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span style="color: #61AFEF;"> _mint</span><span>(</span><span style="color: #E5C07B;">msg.sender</span><span>, SHIELD,</span><span style="color: #D19A66;"> 100</span><span>,</span><span style="color: #98C379;"> &quot;&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span>}</span></span></code></pre> <p>The URI string contains <code>{id}</code>, which gets replaced by the token ID at query time. Token <code>0</code> resolves to <code>item/0.json</code>, token <code>1</code> to <code>item/1.json</code>, and so on. One URI template serves all tokens.</p> <h2 id="key-functions">Key Functions</h2> <h3 id="minting">Minting</h3> <p>Single mint:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> mint</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> to</span><span>,</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> id</span><span>,</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>)</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #61AFEF;"> _mint</span><span>(to, id, amount,</span><span style="color: #98C379;"> &quot;&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span><span>}</span></span></code></pre> <p>Batch mint (this is where gas savings become significant):</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> mintBatch</span><span>(</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #E5C07B;"> address</span><span style="color: #E06C75;font-style: italic;"> to</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span><span style="color: #E5C07B;"> uint256</span><span>[]</span><span style="color: #C678DD;"> memory</span><span style="color: #E06C75;font-style: italic;"> ids</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">4</span><span style="color: #E5C07B;"> uint256</span><span>[]</span><span style="color: #C678DD;"> memory</span><span style="color: #E06C75;font-style: italic;"> amounts</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">5</span><span>)</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">6</span><span style="color: #61AFEF;"> _mintBatch</span><span>(to, ids, amounts,</span><span style="color: #98C379;"> &quot;&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">7</span><span>}</span></span></code></pre> <p>Five tokens in one transaction instead of five.</p> <h3 id="transferring">Transferring</h3> <p>Single transfer:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> safeTransferFrom</span><span>(</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #E5C07B;"> address</span><span style="color: #E06C75;font-style: italic;"> from</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span><span style="color: #E5C07B;"> address</span><span style="color: #E06C75;font-style: italic;"> to</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">4</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> id</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">5</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">6</span><span style="color: #E5C07B;"> bytes</span><span style="color: #C678DD;"> memory</span><span style="color: #E06C75;font-style: italic;"> data</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">7</span><span>)</span><span style="color: #C678DD;"> public</span></span></code></pre> <p>Batch transfer:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> safeBatchTransferFrom</span><span>(</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #E5C07B;"> address</span><span style="color: #E06C75;font-style: italic;"> from</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span><span style="color: #E5C07B;"> address</span><span style="color: #E06C75;font-style: italic;"> to</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">4</span><span style="color: #E5C07B;"> uint256</span><span>[]</span><span style="color: #C678DD;"> memory</span><span style="color: #E06C75;font-style: italic;"> ids</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">5</span><span style="color: #E5C07B;"> uint256</span><span>[]</span><span style="color: #C678DD;"> memory</span><span style="color: #E06C75;font-style: italic;"> amounts</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">6</span><span style="color: #E5C07B;"> bytes</span><span style="color: #C678DD;"> memory</span><span style="color: #E06C75;font-style: italic;"> data</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">7</span><span>)</span><span style="color: #C678DD;"> public</span></span></code></pre><h3 id="checking-balances">Checking Balances</h3> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #7F848E;font-style: italic;">// Single balance</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> balanceOf</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> account</span><span>,</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> id</span><span>)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #C678DD;"> public view returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span>// </span><span style="color: #61AFEF;">Batch balance check</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #61AFEF;">function balanceOfBatch</span><span>(</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #61AFEF;"> address</span><span>[]</span><span style="color: #C678DD;"> memory</span><span style="color: #61AFEF;"> accounts</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #61AFEF;"> uint256</span><span>[]</span><span style="color: #C678DD;"> memory</span><span style="color: #61AFEF;"> ids</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span>)</span><span style="color: #C678DD;"> public view returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>[]</span><span style="color: #C678DD;"> memory</span><span>)</span></span></code></pre> <p>The batch version lets you read multiple balances in a single call.</p> <h2 id="approvals">Approvals</h2> <p>ERC-1155 uses operator-level approval, not per-token approval:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #7F848E;font-style: italic;">// Alice approves Bob to manage ALL her tokens in this contract</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> setApprovalForAll</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> operator</span><span>,</span><span style="color: #E5C07B;"> bool</span><span style="color: #E06C75;font-style: italic;"> approved</span><span>)</span><span style="color: #C678DD;"> public</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">4</span><span>// </span><span style="color: #61AFEF;">Check</span><span style="color: #C678DD;"> if</span><span style="color: #61AFEF;"> Bob is approved</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">5</span><span style="color: #61AFEF;">function isApprovedForAll</span><span>(</span><span style="color: #61AFEF;">address account</span><span>,</span><span style="color: #61AFEF;"> address operator</span><span>)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">6</span><span style="color: #C678DD;"> public view returns</span><span> (</span><span style="color: #E5C07B;">bool</span><span>)</span></span></code></pre> <p>This is all-or-nothing. An approved operator can move any of your tokens in that contract. There is no way to approve access to only one token type. If you need that kind of granularity, ERC-721 per-token approvals are more appropriate.</p> <blockquote class="markdown-alert-warning"> <p>Be careful which addresses you approve as operators. An approved operator can transfer any token you hold in that contract, not just a specific ID.</p> </blockquote> <h2 id="transfer-flow">Transfer Flow</h2> <p>When a transfer is initiated, the contract runs through several checks before updating state:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="plain"><span class="giallo-l"><span>User initiates transfer</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span> Has approval?</span></span> <span class="giallo-l"><span> / \</span></span> <span class="giallo-l"><span> yes no</span></span> <span class="giallo-l"><span> | |</span></span> <span class="giallo-l"><span>Check balance Revert</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span>Enough tokens?</span></span> <span class="giallo-l"><span> / \</span></span> <span class="giallo-l"><span>yes no</span></span> <span class="giallo-l"><span> | |</span></span> <span class="giallo-l"><span>Update Revert</span></span> <span class="giallo-l"><span>balances</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span>Is receiver a contract?</span></span> <span class="giallo-l"><span> / \</span></span> <span class="giallo-l"><span> yes no</span></span> <span class="giallo-l"><span> | |</span></span> <span class="giallo-l"><span>Call receiver Done</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span>Receiver accepts?</span></span> <span class="giallo-l"><span> / \</span></span> <span class="giallo-l"><span> yes no</span></span> <span class="giallo-l"><span> | |</span></span> <span class="giallo-l"><span> Done Revert</span></span></code></pre> <p>The last step matters. If the recipient is a contract, it must implement the receiver interface. Without it, the transfer reverts.</p> <h2 id="receiving-tokens-in-a-contract">Receiving Tokens in a Contract</h2> <p>If your contract needs to receive ERC-1155 tokens, implement <code>IERC1155Receiver</code>:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="ItemVault.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">import</span><span style="color: #98C379;"> &quot;@openzeppelin/contracts/token/ERC1155/IERC1155Receiver.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> ItemVault</span><span style="color: #C678DD;"> is</span><span style="color: #E5C07B;"> IERC1155Receiver</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> onERC1155Received</span><span>(</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #E5C07B;"> address</span><span style="color: #E06C75;font-style: italic;"> operator</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #E5C07B;"> address</span><span style="color: #E06C75;font-style: italic;"> from</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> id</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> value</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #E5C07B;"> bytes</span><span style="color: #C678DD;"> calldata</span><span style="color: #E06C75;font-style: italic;"> data</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span> )</span><span style="color: #C678DD;"> external returns</span><span> (</span><span style="color: #E5C07B;">bytes4</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span style="color: #7F848E;font-style: italic;"> // Handle single token receipt</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span style="color: #C678DD;"> return</span><span style="color: #E5C07B;"> this</span><span>.onERC1155Received.selector;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> onERC1155BatchReceived</span><span>(</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span style="color: #E5C07B;"> address</span><span style="color: #E06C75;font-style: italic;"> operator</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">17</span><span style="color: #E5C07B;"> address</span><span style="color: #E06C75;font-style: italic;"> from</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">18</span><span style="color: #E5C07B;"> uint256</span><span>[]</span><span style="color: #C678DD;"> calldata</span><span style="color: #E06C75;font-style: italic;"> ids</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">19</span><span style="color: #E5C07B;"> uint256</span><span>[]</span><span style="color: #C678DD;"> calldata</span><span style="color: #E06C75;font-style: italic;"> values</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">20</span><span style="color: #E5C07B;"> bytes</span><span style="color: #C678DD;"> calldata</span><span style="color: #E06C75;font-style: italic;"> data</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">21</span><span> )</span><span style="color: #C678DD;"> external returns</span><span> (</span><span style="color: #E5C07B;">bytes4</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">22</span><span style="color: #C678DD;"> return</span><span style="color: #E5C07B;"> this</span><span>.onERC1155BatchReceived.selector;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">23</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">24</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">25</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> supportsInterface</span><span>(</span><span style="color: #E5C07B;">bytes4</span><span style="color: #E06C75;font-style: italic;"> interfaceId</span><span>)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">26</span><span style="color: #C678DD;"> external pure returns</span><span> (</span><span style="color: #E5C07B;">bool</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">27</span><span style="color: #C678DD;"> return</span><span> interfaceId ==</span><span style="color: #E5C07B;"> type</span><span>(IERC1155Receiver).interfaceId;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">28</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">29</span><span>}</span></span></code></pre> <p>Returning the correct selector signals to the sending contract that the receiver accepted the tokens intentionally. If you skip this interface, any <code>safeTransfer</code> to your contract will revert.</p> <h2 id="a-real-example-rpg-crafting-system">A Real Example: RPG Crafting System</h2> <p>Here is a more complete contract that lets you create token types on the fly and implement a crafting mechanic:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="RPGItems.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #7F848E;font-style: italic;">// SPDX-License-Identifier: MIT</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;">pragma</span><span style="color: #E06C75;"> solidity</span><span style="color: #D19A66;"> ^0.8.0</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;">import</span><span style="color: #98C379;"> &quot;@openzeppelin/contracts/token/ERC1155/ERC1155.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> RPGItems</span><span style="color: #C678DD;"> is</span><span style="color: #E5C07B;"> ERC1155</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #E5C07B;"> uint256</span><span style="color: #C678DD;"> private</span><span> _currentTokenID </span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> 0</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #C678DD;"> mapping</span><span>(</span><span style="color: #E5C07B;">uint256</span><span> =&gt;</span><span style="color: #E5C07B;"> uint256</span><span>)</span><span style="color: #C678DD;"> public</span><span> tokenSupply;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #C678DD;"> mapping</span><span>(</span><span style="color: #E5C07B;">uint256</span><span> =&gt;</span><span style="color: #E5C07B;"> bool</span><span>)</span><span style="color: #C678DD;"> public</span><span> isNFT;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span style="color: #C678DD;"> constructor</span><span>()</span><span style="color: #61AFEF;"> ERC1155</span><span>(&quot;https://rpg.game/items/{id}&quot;) {}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> createToken</span><span>(</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> supply</span><span>,</span><span style="color: #E5C07B;"> bool</span><span style="color: #E06C75;font-style: italic;"> nft</span><span>)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span style="color: #C678DD;"> external returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">17</span><span style="color: #E5C07B;"> uint256</span><span> id </span><span style="color: #56B6C2;">=</span><span> _currentTokenID;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">18</span><span> _currentTokenID</span><span style="color: #56B6C2;">++</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">19</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">20</span><span> isNFT[id]</span><span style="color: #56B6C2;"> =</span><span> nft;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">21</span><span> tokenSupply[id]</span><span style="color: #56B6C2;"> =</span><span> supply;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">22</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">23</span><span style="color: #61AFEF;"> _mint</span><span>(</span><span style="color: #E5C07B;">msg.sender</span><span>, id, supply,</span><span style="color: #98C379;"> &quot;&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">24</span><span style="color: #C678DD;"> return</span><span> id;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">25</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">26</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">27</span><span style="color: #7F848E;font-style: italic;"> // Burn a set of materials and mint the crafted result</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">28</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> craft</span><span>(</span><span style="color: #E5C07B;">uint256</span><span>[]</span><span style="color: #C678DD;"> memory</span><span style="color: #E06C75;font-style: italic;"> materials</span><span>,</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> result</span><span>)</span><span style="color: #C678DD;"> external</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">29</span><span style="color: #E5C07B;"> uint256</span><span>[]</span><span style="color: #C678DD;"> memory</span><span> amounts </span><span style="color: #56B6C2;">=</span><span style="color: #61AFEF;"> _ones</span><span>(materials.length);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">30</span><span style="color: #61AFEF;"> _burnBatch</span><span>(</span><span style="color: #E5C07B;">msg.sender</span><span>, materials, amounts);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">31</span><span style="color: #61AFEF;"> _mint</span><span>(</span><span style="color: #E5C07B;">msg.sender</span><span>, result,</span><span style="color: #D19A66;"> 1</span><span>,</span><span style="color: #98C379;"> &quot;&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">32</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">33</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">34</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> _ones</span><span>(</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> length</span><span>)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">35</span><span style="color: #C678DD;"> private pure returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>[]</span><span style="color: #C678DD;"> memory</span><span>)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">36</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">37</span><span style="color: #E5C07B;"> uint256</span><span>[]</span><span style="color: #C678DD;"> memory</span><span> amounts </span><span style="color: #56B6C2;">=</span><span style="color: #C678DD;"> new</span><span style="color: #E5C07B;"> uint256</span><span>[](</span><span style="color: #E06C75;font-style: italic;">length</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">38</span><span style="color: #C678DD;"> for</span><span> (</span><span style="color: #E5C07B;">uint256</span><span> i </span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> 0</span><span>; i &lt; length; i</span><span style="color: #56B6C2;">++</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">39</span><span> amounts[i]</span><span style="color: #56B6C2;"> =</span><span style="color: #D19A66;"> 1</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">40</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">41</span><span style="color: #C678DD;"> return</span><span> amounts;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">42</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">43</span><span>}</span></span></code></pre> <p><code>createToken</code> registers a new token type and mints the full supply to the caller. Pass <code>supply = 1</code> for an NFT, or any higher number for a fungible or semi-fungible token. <code>craft</code> burns a list of input materials and mints the output item. One transaction covers both sides of the operation.</p> <h2 id="metadata-structure">Metadata Structure</h2> <p>The JSON metadata for each token follows this structure:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span style="color: #E06C75;"> &quot;name&quot;</span><span>:</span><span style="color: #98C379;"> &quot;Fire Sword&quot;</span><span>,</span></span> <span class="giallo-l"><span style="color: #E06C75;"> &quot;description&quot;</span><span>:</span><span style="color: #98C379;"> &quot;A legendary blade forged in dragon fire&quot;</span><span>,</span></span> <span class="giallo-l"><span style="color: #E06C75;"> &quot;image&quot;</span><span>:</span><span style="color: #98C379;"> &quot;https://game.example/images/fire-sword.png&quot;</span><span>,</span></span> <span class="giallo-l"><span style="color: #E06C75;"> &quot;properties&quot;</span><span>: {</span></span> <span class="giallo-l"><span style="color: #E06C75;"> &quot;damage&quot;</span><span>:</span><span style="color: #D19A66;"> 150</span><span>,</span></span> <span class="giallo-l"><span style="color: #E06C75;"> &quot;element&quot;</span><span>:</span><span style="color: #98C379;"> &quot;fire&quot;</span><span>,</span></span> <span class="giallo-l"><span style="color: #E06C75;"> &quot;rarity&quot;</span><span>:</span><span style="color: #98C379;"> &quot;legendary&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The contract URI template handles routing. You host one JSON file per token ID at the path your URI template describes.</p> <h2 id="gas-savings-in-practice">Gas Savings in Practice</h2> <p>Transferring five different token types to one address:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="plain"><span class="giallo-l"><span>With separate ERC-20 / ERC-721 contracts:</span></span> <span class="giallo-l"><span> Transaction 1: Transfer token A (21,000 base gas + execution)</span></span> <span class="giallo-l"><span> Transaction 2: Transfer token B (21,000 base gas + execution)</span></span> <span class="giallo-l"><span> Transaction 3: Transfer token C (21,000 base gas + execution)</span></span> <span class="giallo-l"><span> Transaction 4: Transfer token D (21,000 base gas + execution)</span></span> <span class="giallo-l"><span> Transaction 5: Transfer token E (21,000 base gas + execution)</span></span> <span class="giallo-l"><span> Total base gas: ~105,000</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>With ERC-1155 safeBatchTransferFrom:</span></span> <span class="giallo-l"><span> Transaction 1: Transfer all 5 (21,000 base gas + batch execution)</span></span> <span class="giallo-l"><span> Total base gas: ~21,000</span></span></code></pre> <p>The batch execution cost is higher than a single transfer, but the five separate base fees disappear. At scale, or when gas prices are elevated, this difference matters.</p> <p>Minting is where the savings are even more dramatic. Minting 100 different token types with ERC-20 or ERC-721 requires 100 deployments plus 100 mint transactions. With ERC-1155, you deploy once and call <code>mintBatch</code> once.</p> <h2 id="comparing-the-standards">Comparing the Standards</h2> <table><thead><tr><th>Feature</th><th>ERC-20</th><th>ERC-721</th><th>ERC-1155</th></tr></thead><tbody> <tr><td>Token types per contract</td><td>1</td><td>1</td><td>Unlimited</td></tr> <tr><td>Fungibility</td><td>Yes</td><td>No</td><td>Both</td></tr> <tr><td>Batch transfers</td><td>No</td><td>No</td><td>Yes</td></tr> <tr><td>Gas efficiency</td><td>Medium</td><td>Medium</td><td>High</td></tr> <tr><td>Per-token metadata</td><td>No</td><td>Yes</td><td>Yes</td></tr> <tr><td>Approval granularity</td><td>Amount</td><td>Per token</td><td>Operator</td></tr> <tr><td>Best for</td><td>Currency</td><td>Unique assets</td><td>Mixed assets</td></tr> </tbody></table> <h3 id="when-to-use-erc-20">When to use ERC-20</h3> <p>Use ERC-20 when you need one fungible token and maximum compatibility with DeFi protocols. Lending platforms, AMMs, and governance systems all expect ERC-20. Using ERC-1155 here adds complexity without benefit.</p> <h3 id="when-to-use-erc-721">When to use ERC-721</h3> <p>Use ERC-721 when every token must be unique and you want per-token approval control. Art platforms, domain name registries, and collectibles benefit from ERC-721's tighter ownership semantics and broad marketplace support.</p> <h3 id="when-to-use-erc-1155">When to use ERC-1155</h3> <p>Use ERC-1155 when you need multiple token types in one contract, especially when those types include both fungible and non-fungible tokens. Gaming inventories, digital item systems, and any application doing batch operations are the main use cases.</p> <h2 id="the-tradeoffs">The Tradeoffs</h2> <p>ERC-1155 is flexible, but flexibility has a cost.</p> <p>The operator approval model is coarser than ERC-721. You cannot approve an address to move only your swords but not your gold. Any operator gets full access to everything you hold in that contract. If approval granularity matters, this is a real limitation.</p> <p>The balance mapping is two-dimensional. Tools, indexers, and wallets that were built for ERC-20 or ERC-721 do not automatically support ERC-1155. Marketplace support has improved significantly, but it is still not as universal as ERC-721 for NFTs.</p> <p>There is also an argument for simplicity. A contract that manages one token type is easier to audit than one that manages hundreds. For a simple payment token, deploying ERC-1155 is unnecessary complexity.</p> <h2 id="conclusion">Conclusion</h2> <p>ERC-1155 is the right standard when a single contract needs to manage multiple token types. It reduces deployment cost, cuts gas on batch operations, and handles fungible, non-fungible, and semi-fungible tokens without separate contracts for each.</p> <p>For single-purpose tokens, ERC-20 and ERC-721 remain the cleaner choice. But for gaming, digital item systems, or any application mixing token types, ERC-1155 is the practical option.</p> 2025-11-21T00:00:00+00:00 2025-11-21T00:00:00+00:00 Akash Vaghela https://akash11.com/blog/erc-20-the-standard-that-powers-most-crypto-tokens/ <p>ERC-20 is a technical standard that defines how tokens behave on Ethereum. It specifies a common interface so that any wallet, exchange, or smart contract can interact with any ERC-20 token without custom integration code.</p> <p>This post covers what ERC-20 requires, how each function and event works, the approve-and-transfer pattern used in DeFi, and the known weaknesses of the standard.</p> <h2 id="what-erc-20-actually-is">What ERC-20 Actually Is</h2> <p>ERC stands for "Ethereum Request for Comments". ERC-20 was proposed in November 2015 by Fabian Vogelsteller. Before this standard existed, every token on Ethereum had different function names and different behavior. Wallets and exchanges had to write custom code for each token they wanted to support. That was not scalable.</p> <p>ERC-20 solved this by defining a minimal, shared interface. Any contract that implements the six required functions and two required events is an ERC-20 token. That is the entire requirement. The standard says nothing about what the token represents, who can hold it, or how it is created.</p> <p>Today, the most widely used tokens on Ethereum follow this standard: USDT, USDC, LINK, UNI, and thousands of others.</p> <h2 id="the-six-required-functions">The Six Required Functions</h2> <h3 id="totalsupply"><code>totalSupply()</code></h3> <p>Returns the total number of tokens that exist.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> totalSupply</span><span>()</span><span style="color: #C678DD;"> public view returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>)</span></span></code></pre> <p>If a token launched with 1 million tokens, this returns <code>1000000000000000000000000</code> (accounting for 18 decimals). More on decimals below.</p> <h3 id="balanceof-address"><code>balanceOf(address)</code></h3> <p>Returns the number of tokens held by a specific address.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> balanceOf</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> account</span><span>)</span><span style="color: #C678DD;"> public view returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>)</span></span></code></pre> <p>This is how wallets display your token balance. Every balance query goes through this function.</p> <h3 id="transfer-address-uint256"><code>transfer(address, uint256)</code></h3> <p>Sends tokens from the caller's address to another address.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> transfer</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> recipient</span><span>,</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>)</span><span style="color: #C678DD;"> public returns</span><span> (</span><span style="color: #E5C07B;">bool</span><span>)</span></span></code></pre> <p>The function must return <code>true</code> on success. It must revert (or return <code>false</code>) if the caller does not have enough tokens. It must also emit a <code>Transfer</code> event.</p> <h3 id="approve-address-uint256"><code>approve(address, uint256)</code></h3> <p>Authorizes another address to spend tokens on your behalf, up to a specified amount.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> approve</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> spender</span><span>,</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>)</span><span style="color: #C678DD;"> public returns</span><span> (</span><span style="color: #E5C07B;">bool</span><span>)</span></span></code></pre> <p>This is the first step in the delegated transfer pattern used across DeFi. You are not moving tokens here. You are setting a permission. The actual transfer happens later.</p> <h3 id="allowance-address-address"><code>allowance(address, address)</code></h3> <p>Returns how many tokens a spender is still allowed to move on behalf of an owner.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> allowance</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> owner</span><span>,</span><span style="color: #E5C07B;"> address</span><span style="color: #E06C75;font-style: italic;"> spender</span><span>)</span><span style="color: #C678DD;"> public view returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>)</span></span></code></pre> <p>After you approve a spender for 100 tokens and they transfer 40, <code>allowance(yourAddress, spenderAddress)</code> returns <code>60</code>.</p> <h3 id="transferfrom-address-address-uint256"><code>transferFrom(address, address, uint256)</code></h3> <p>Transfers tokens from one address to another, using an existing allowance.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> transferFrom</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> sender</span><span>,</span><span style="color: #E5C07B;"> address</span><span style="color: #E06C75;font-style: italic;"> recipient</span><span>,</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>)</span><span style="color: #C678DD;"> public returns</span><span> (</span><span style="color: #E5C07B;">bool</span><span>)</span></span></code></pre> <p>The caller of this function must have an allowance from <code>sender</code> that covers <code>amount</code>. This is what a DEX or lending protocol calls after you have approved it.</p> <h2 id="the-two-required-events">The Two Required Events</h2> <p>Events let off-chain applications track what happens on-chain without polling the blockchain constantly.</p> <h3 id="transfer"><code>Transfer</code></h3> <p>Emitted whenever tokens move between addresses.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #C678DD;">event</span><span style="color: #E5C07B;"> Transfer</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #C678DD;"> indexed</span><span style="color: #E06C75;font-style: italic;"> from</span><span>, </span><span style="color: #E5C07B;">address</span><span style="color: #C678DD;"> indexed</span><span style="color: #E06C75;font-style: italic;"> to</span><span>, </span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> value</span><span>)</span></span></code></pre> <p>When new tokens are minted, <code>from</code> is the zero address. When tokens are burned, <code>to</code> is the zero address. This convention lets indexers detect minting and burning without additional logic.</p> <h3 id="approval"><code>Approval</code></h3> <p>Emitted whenever <code>approve()</code> is called.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #C678DD;">event</span><span style="color: #E5C07B;"> Approval</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #C678DD;"> indexed</span><span style="color: #E06C75;font-style: italic;"> owner</span><span>, </span><span style="color: #E5C07B;">address</span><span style="color: #C678DD;"> indexed</span><span style="color: #E06C75;font-style: italic;"> spender</span><span>, </span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> value</span><span>)</span></span></code></pre><h2 id="a-minimal-working-implementation">A Minimal Working Implementation</h2> <p>Here is a complete ERC-20 implementation with no external dependencies:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="SimpleToken.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #7F848E;font-style: italic;">// SPDX-License-Identifier: MIT</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;">pragma</span><span style="color: #E06C75;"> solidity</span><span style="color: #D19A66;"> ^0.8.0</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> SimpleToken</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #E5C07B;"> string</span><span style="color: #C678DD;"> public</span><span> name </span><span style="color: #56B6C2;">=</span><span style="color: #98C379;"> &quot;Simple Token&quot;</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #E5C07B;"> string</span><span style="color: #C678DD;"> public</span><span> symbol </span><span style="color: #56B6C2;">=</span><span style="color: #98C379;"> &quot;SMP&quot;</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #E5C07B;"> uint8</span><span style="color: #C678DD;"> public</span><span> decimals </span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> 18</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #E5C07B;"> uint256</span><span style="color: #C678DD;"> private</span><span> _totalSupply;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #C678DD;"> mapping</span><span>(</span><span style="color: #E5C07B;">address</span><span> =&gt;</span><span style="color: #E5C07B;"> uint256</span><span>)</span><span style="color: #C678DD;"> private</span><span> _balances;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span style="color: #C678DD;"> mapping</span><span>(</span><span style="color: #E5C07B;">address</span><span> =&gt;</span><span style="color: #C678DD;"> mapping</span><span>(</span><span style="color: #E5C07B;">address</span><span> =&gt;</span><span style="color: #E5C07B;"> uint256</span><span>))</span><span style="color: #C678DD;"> private</span><span> _allowances;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span style="color: #C678DD;"> event</span><span style="color: #E5C07B;"> Transfer</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #C678DD;"> indexed</span><span style="color: #E06C75;font-style: italic;"> from</span><span>, </span><span style="color: #E5C07B;">address</span><span style="color: #C678DD;"> indexed</span><span style="color: #E06C75;font-style: italic;"> to</span><span>, </span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> value</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span style="color: #C678DD;"> event</span><span style="color: #E5C07B;"> Approval</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #C678DD;"> indexed</span><span style="color: #E06C75;font-style: italic;"> owner</span><span>, </span><span style="color: #E5C07B;">address</span><span style="color: #C678DD;"> indexed</span><span style="color: #E06C75;font-style: italic;"> spender</span><span>, </span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> value</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span style="color: #C678DD;"> constructor</span><span>(</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> initialSupply</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">17</span><span> _totalSupply </span><span style="color: #56B6C2;">=</span><span> initialSupply;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">18</span><span> _balances[</span><span style="color: #E5C07B;">msg.sender</span><span>]</span><span style="color: #56B6C2;"> =</span><span> initialSupply;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">19</span><span style="color: #7F848E;font-style: italic;"> // Mint event: from is zero address</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">20</span><span style="color: #C678DD;"> emit</span><span style="color: #61AFEF;"> Transfer</span><span>(</span><span style="color: #E5C07B;">address</span><span>(</span><span style="color: #D19A66;">0</span><span>),</span><span style="color: #E5C07B;"> msg.sender</span><span>, initialSupply);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">21</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">22</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">23</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> totalSupply</span><span>()</span><span style="color: #C678DD;"> public view returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">24</span><span style="color: #C678DD;"> return</span><span> _totalSupply;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">25</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">26</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">27</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> balanceOf</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> account</span><span>)</span><span style="color: #C678DD;"> public view returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">28</span><span style="color: #C678DD;"> return</span><span> _balances[account];</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">29</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">30</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">31</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> transfer</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> recipient</span><span>,</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>)</span><span style="color: #C678DD;"> public returns</span><span> (</span><span style="color: #E5C07B;">bool</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">32</span><span style="color: #C678DD;"> require</span><span>(_balances[</span><span style="color: #E5C07B;">msg.sender</span><span>] &gt;</span><span style="color: #56B6C2;">=</span><span> amount,</span><span style="color: #98C379;"> &quot;Insufficient balance&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">33</span><span> _balances[</span><span style="color: #E5C07B;">msg.sender</span><span>]</span><span style="color: #56B6C2;"> -=</span><span> amount;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">34</span><span> _balances[recipient]</span><span style="color: #56B6C2;"> +=</span><span> amount;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">35</span><span style="color: #C678DD;"> emit</span><span style="color: #61AFEF;"> Transfer</span><span>(</span><span style="color: #E5C07B;">msg.sender</span><span>, recipient, amount);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">36</span><span style="color: #C678DD;"> return</span><span style="color: #D19A66;"> true</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">37</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">38</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">39</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> approve</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> spender</span><span>,</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>)</span><span style="color: #C678DD;"> public returns</span><span> (</span><span style="color: #E5C07B;">bool</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">40</span><span> _allowances[</span><span style="color: #E5C07B;">msg.sender</span><span>][spender]</span><span style="color: #56B6C2;"> =</span><span> amount;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">41</span><span style="color: #C678DD;"> emit</span><span style="color: #61AFEF;"> Approval</span><span>(</span><span style="color: #E5C07B;">msg.sender</span><span>, spender, amount);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">42</span><span style="color: #C678DD;"> return</span><span style="color: #D19A66;"> true</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">43</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">44</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">45</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> allowance</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> owner</span><span>,</span><span style="color: #E5C07B;"> address</span><span style="color: #E06C75;font-style: italic;"> spender</span><span>)</span><span style="color: #C678DD;"> public view returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">46</span><span style="color: #C678DD;"> return</span><span> _allowances[owner][spender];</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">47</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">48</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">49</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> transferFrom</span><span>(</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">50</span><span style="color: #E5C07B;"> address</span><span style="color: #E06C75;font-style: italic;"> sender</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">51</span><span style="color: #E5C07B;"> address</span><span style="color: #E06C75;font-style: italic;"> recipient</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">52</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> amount</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">53</span><span> )</span><span style="color: #C678DD;"> public returns</span><span> (</span><span style="color: #E5C07B;">bool</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">54</span><span style="color: #C678DD;"> require</span><span>(_balances[sender] &gt;</span><span style="color: #56B6C2;">=</span><span> amount,</span><span style="color: #98C379;"> &quot;Insufficient balance&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">55</span><span style="color: #C678DD;"> require</span><span>(_allowances[sender][</span><span style="color: #E5C07B;">msg.sender</span><span>] &gt;</span><span style="color: #56B6C2;">=</span><span> amount,</span><span style="color: #98C379;"> &quot;Allowance exceeded&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">56</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">57</span><span> _balances[sender]</span><span style="color: #56B6C2;"> -=</span><span> amount;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">58</span><span> _balances[recipient]</span><span style="color: #56B6C2;"> +=</span><span> amount;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">59</span><span> _allowances[sender][</span><span style="color: #E5C07B;">msg.sender</span><span>]</span><span style="color: #56B6C2;"> -=</span><span> amount;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">60</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">61</span><span style="color: #C678DD;"> emit</span><span style="color: #61AFEF;"> Transfer</span><span>(sender, recipient, amount);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">62</span><span style="color: #C678DD;"> return</span><span style="color: #D19A66;"> true</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">63</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">64</span><span>}</span></span></code></pre> <p>This contract is functional but not production-ready. For real deployments, use a battle-tested implementation like OpenZeppelin's <code>ERC20.sol</code>, which handles edge cases this example skips.</p> <h2 id="optional-metadata-functions">Optional Metadata Functions</h2> <p>The standard does not require these, but nearly every token includes them:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> name</span><span>()</span><span style="color: #C678DD;"> public view returns</span><span> (</span><span style="color: #E5C07B;">string</span><span style="color: #C678DD;"> memory</span><span>)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #61AFEF;">function symbol</span><span>()</span><span style="color: #C678DD;"> public view returns</span><span> (</span><span style="color: #E5C07B;">string</span><span style="color: #C678DD;"> memory</span><span>)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span><span style="color: #61AFEF;">function decimals</span><span>()</span><span style="color: #C678DD;"> public view returns</span><span> (</span><span style="color: #E5C07B;">uint8</span><span>)</span></span></code></pre> <p>The <code>decimals</code> value is important. Most tokens use <code>18</code>, matching Ether. This means that <code>1</code> token in human terms is stored as <code>1000000000000000000</code> in the contract. When you send <code>1.5 SMP</code>, you are actually passing <code>1500000000000000000</code> to <code>transfer()</code>. Your wallet handles this conversion so you do not have to.</p> <p>Some tokens use different values. USDC uses <code>6</code> decimals. This is a design choice, not a mistake.</p> <h2 id="the-approve-transferfrom-pattern">The Approve-TransferFrom Pattern</h2> <p>This two-step flow is used in every major DeFi protocol.</p> <p><strong>Step 1:</strong> You call <code>approve(dexAddress, amount)</code> on the token contract. This sets an allowance.</p> <p><strong>Step 2:</strong> The DEX calls <code>transferFrom(yourAddress, poolAddress, amount)</code> when you execute a trade.</p> <p>Why two steps? Because the token contract must be the one to move funds. The DEX cannot take your tokens without your prior authorization. The approve step is that authorization.</p> <p>In practice, many wallets prompt you to approve an unlimited amount (<code>type(uint256).max</code>) so you only pay the gas cost once. This is a UX tradeoff with real security implications: if the spender contract is ever exploited, all your approved tokens are at risk.</p> <h2 id="minting-and-burning">Minting and Burning</h2> <p>These operations are not in the ERC-20 standard, but most real tokens need them.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="MintBurn.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> mint</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> account</span><span>,</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>)</span><span style="color: #C678DD;"> public</span><span style="color: #61AFEF;"> onlyOwner</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span> _totalSupply </span><span style="color: #56B6C2;">+=</span><span> amount;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span> _balances[account]</span><span style="color: #56B6C2;"> +=</span><span> amount;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #7F848E;font-style: italic;"> // from = zero address signals a mint</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #C678DD;"> emit</span><span style="color: #61AFEF;"> Transfer</span><span>(</span><span style="color: #E5C07B;">address</span><span>(</span><span style="color: #D19A66;">0</span><span>), account, amount);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> burn</span><span>(</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>)</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #C678DD;"> require</span><span>(_balances[</span><span style="color: #E5C07B;">msg.sender</span><span>] &gt;</span><span style="color: #56B6C2;">=</span><span> amount,</span><span style="color: #98C379;"> &quot;Insufficient balance&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span> _balances[</span><span style="color: #E5C07B;">msg.sender</span><span>]</span><span style="color: #56B6C2;"> -=</span><span> amount;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span> _totalSupply </span><span style="color: #56B6C2;">-=</span><span> amount;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span style="color: #7F848E;font-style: italic;"> // to = zero address signals a burn</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span style="color: #C678DD;"> emit</span><span style="color: #61AFEF;"> Transfer</span><span>(</span><span style="color: #E5C07B;">msg.sender</span><span>,</span><span style="color: #E5C07B;"> address</span><span>(</span><span style="color: #D19A66;">0</span><span>), amount);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span>}</span></span></code></pre> <p>The convention of emitting <code>Transfer</code> with the zero address is not in the spec, but it is universally followed. Indexers and block explorers rely on it to correctly display total supply changes.</p> <h2 id="known-weaknesses">Known Weaknesses</h2> <h3 id="the-approval-race-condition">The Approval Race Condition</h3> <p>Suppose you have approved a spender for 100 tokens. You then call <code>approve()</code> again to change it to 50. There is a window between your first transaction and the second where a watching spender can front-run you: spend the original 100 before the new approval lands, then spend 50 more after. Total damage: 150 tokens.</p> <p>The safe mitigation is to set the allowance to <code>0</code> first, then set it to the new value in a second transaction.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #61AFEF;">approve</span><span>(spenderAddress,</span><span style="color: #D19A66;"> 0</span><span>);</span><span style="color: #7F848E;font-style: italic;"> // First transaction</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #61AFEF;">approve</span><span>(spenderAddress,</span><span style="color: #D19A66;"> 50</span><span>);</span><span style="color: #7F848E;font-style: italic;"> // Second transaction</span></span></code></pre> <p>Some protocols add <code>increaseAllowance</code> and <code>decreaseAllowance</code> helpers to make this cleaner, but these are also not part of the standard.</p> <h3 id="lost-tokens-in-contracts">Lost Tokens in Contracts</h3> <p>If you send ERC-20 tokens to a contract address that has no code to handle them, those tokens are stuck. The contract does not get notified that it received tokens. It cannot reject them. They are permanently inaccessible.</p> <p>This is a real problem. Millions of dollars in tokens have been lost this way. ERC-223 and ERC-777 both tried to solve it by adding a callback mechanism, but neither gained the same adoption as ERC-20.</p> <blockquote class="markdown-alert-warning"> <p>Always verify you are sending tokens to an address that can handle them. Sending ERC-20 tokens to a contract that has no withdrawal function results in permanent loss.</p> </blockquote> <h3 id="no-transfer-notification">No Transfer Notification</h3> <p>Related to the above: contracts do not know when they receive ERC-20 tokens. If your contract needs to react to incoming tokens (trigger a swap, update accounting), you cannot rely on a callback. You have to build a separate deposit function that calls <code>transferFrom</code>, or instruct users to call a function after transferring.</p> <h2 id="when-erc-20-is-the-right-choice">When ERC-20 Is the Right Choice</h2> <p>ERC-20 is the right choice when you need a fungible token that works everywhere Ethereum infrastructure exists: wallets, DEXs, bridges, lending protocols, and block explorers.</p> <p>It is not the right choice when you need:</p> <ul> <li>Non-fungible tokens (use ERC-721 or ERC-1155)</li> <li>Tokens with transfer hooks or callbacks (ERC-777 exists but has known reentrancy risks)</li> <li>Gas-efficient multi-token contracts (ERC-1155 is better here)</li> </ul> <p>The standard's simplicity is also its main limitation. It does exactly what it specifies, nothing more. Any behavior beyond the six functions and two events is your responsibility to implement correctly.</p> 2025-11-21T00:00:00+00:00 2025-11-21T00:00:00+00:00 Akash Vaghela https://akash11.com/blog/erc-721-the-token-standard-that-powers-nfts/ <p>ERC-721 is the Ethereum token standard for non-fungible tokens. Each ERC-721 token is unique and indivisible. No two tokens are interchangeable, and you cannot split one into smaller units.</p> <p>This post covers how the standard works, what you must implement to be compliant, how metadata attaches to tokens, and how ERC-721 compares to ERC-20 and ERC-1155.</p> <h2 id="what-non-fungible-means">What Non-Fungible Means</h2> <p>With ERC-20, all tokens are identical. One USDC is the same as any other USDC. You can add, subtract, and split them freely.</p> <p>With ERC-721, token <code>#1</code> is completely different from token <code>#2</code>. Each has its own identity, its own owner, and its own value. You cannot send half a token. You transfer the whole thing or nothing.</p> <p>This makes ERC-721 useful for representing things that are inherently unique: artworks, domain names, game items, event tickets, and certificates of ownership.</p> <h2 id="the-core-interface">The Core Interface</h2> <p>Every ERC-721 contract must implement this interface:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">interface</span><span style="color: #E5C07B;"> IERC721</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> balanceOf</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> owner</span><span>)</span><span style="color: #C678DD;"> external view returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> ownerOf</span><span>(</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> tokenId</span><span>)</span><span style="color: #C678DD;"> external view returns</span><span> (</span><span style="color: #E5C07B;">address</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> transferFrom</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> from</span><span>,</span><span style="color: #E5C07B;"> address</span><span style="color: #E06C75;font-style: italic;"> to</span><span>,</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> tokenId</span><span>)</span><span style="color: #C678DD;"> external</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> approve</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> to</span><span>,</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> tokenId</span><span>)</span><span style="color: #C678DD;"> external</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> getApproved</span><span>(</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> tokenId</span><span>)</span><span style="color: #C678DD;"> external view returns</span><span> (</span><span style="color: #E5C07B;">address</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> setApprovalForAll</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> operator</span><span>,</span><span style="color: #E5C07B;"> bool</span><span style="color: #E06C75;font-style: italic;"> approved</span><span>)</span><span style="color: #C678DD;"> external</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> isApprovedForAll</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> owner</span><span>,</span><span style="color: #E5C07B;"> address</span><span style="color: #E06C75;font-style: italic;"> operator</span><span>)</span><span style="color: #C678DD;"> external view returns</span><span> (</span><span style="color: #E5C07B;">bool</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span>}</span></span></code></pre> <p>Here is what each function does:</p> <p><code>balanceOf</code> returns the number of tokens an address owns. It is a count, not a value.</p> <p><code>ownerOf</code> takes a token ID and returns the address that owns it. Every token has exactly one owner.</p> <p><code>transferFrom</code> moves a token from one address to another. The caller must be the owner or have approval.</p> <p><code>approve</code> lets you authorize a specific address to transfer a single token on your behalf.</p> <p><code>setApprovalForAll</code> grants an operator permission to manage all your tokens in one call.</p> <p><code>getApproved</code> and <code>isApprovedForAll</code> are the corresponding read functions to check those permissions.</p> <h2 id="a-basic-implementation">A Basic Implementation</h2> <p>Here is a minimal contract showing how the core mechanics work:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="SimpleNFT.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> SimpleNFT</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;"> mapping</span><span>(</span><span style="color: #E5C07B;">uint256</span><span> =&gt;</span><span style="color: #E5C07B;"> address</span><span>)</span><span style="color: #C678DD;"> private</span><span> owners;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #C678DD;"> mapping</span><span>(</span><span style="color: #E5C07B;">address</span><span> =&gt;</span><span style="color: #E5C07B;"> uint256</span><span>)</span><span style="color: #C678DD;"> private</span><span> balances;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;"> mapping</span><span>(</span><span style="color: #E5C07B;">uint256</span><span> =&gt;</span><span style="color: #E5C07B;"> address</span><span>)</span><span style="color: #C678DD;"> private</span><span> tokenApprovals;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #E5C07B;"> uint256</span><span style="color: #C678DD;"> private</span><span> nextTokenId;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> mint</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> to</span><span>)</span><span style="color: #C678DD;"> external returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #E5C07B;"> uint256</span><span> tokenId </span><span style="color: #56B6C2;">=</span><span> nextTokenId;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span> nextTokenId</span><span style="color: #56B6C2;">++</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span> owners[tokenId]</span><span style="color: #56B6C2;"> =</span><span> to;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span> balances[to]</span><span style="color: #56B6C2;">++</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span style="color: #C678DD;"> return</span><span> tokenId;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">17</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">18</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> ownerOf</span><span>(</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> tokenId</span><span>)</span><span style="color: #C678DD;"> external view returns</span><span> (</span><span style="color: #E5C07B;">address</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">19</span><span style="color: #E5C07B;"> address</span><span> owner </span><span style="color: #56B6C2;">=</span><span> owners[tokenId];</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">20</span><span style="color: #C678DD;"> require</span><span>(owner !=</span><span style="color: #E5C07B;"> address</span><span>(</span><span style="color: #D19A66;">0</span><span>),</span><span style="color: #98C379;"> &quot;Token does not exist&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">21</span><span style="color: #C678DD;"> return</span><span> owner;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">22</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">23</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">24</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> transferFrom</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> from</span><span>,</span><span style="color: #E5C07B;"> address</span><span style="color: #E06C75;font-style: italic;"> to</span><span>,</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> tokenId</span><span>)</span><span style="color: #C678DD;"> external</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">25</span><span style="color: #C678DD;"> require</span><span>(owners[tokenId] == from,</span><span style="color: #98C379;"> &quot;Not the owner&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">26</span><span style="color: #C678DD;"> require</span><span>(</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">27</span><span style="color: #E5C07B;"> msg.sender</span><span> == from || tokenApprovals[tokenId] ==</span><span style="color: #E5C07B;"> msg.sender</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">28</span><span style="color: #98C379;"> &quot;Not approved&quot;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">29</span><span> );</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">30</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">31</span><span> balances[from]</span><span style="color: #56B6C2;">--</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">32</span><span> balances[to]</span><span style="color: #56B6C2;">++</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">33</span><span> owners[tokenId]</span><span style="color: #56B6C2;"> =</span><span> to;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">34</span><span style="color: #C678DD;"> delete</span><span> tokenApprovals[tokenId];</span><span style="color: #7F848E;font-style: italic;"> // Clear approval after transfer</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">35</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">36</span><span>}</span></span></code></pre> <p>Three mappings power this contract. <code>owners</code> tracks which address holds each token ID. <code>balances</code> counts how many tokens each address owns. <code>tokenApprovals</code> stores per-token approvals.</p> <p>Notice that <code>transferFrom</code> deletes the token approval at the end. This is required by the standard. Leaving stale approvals would let a previously approved address transfer a token after the owner has already moved it.</p> <h2 id="token-metadata">Token Metadata</h2> <p>ERC-721 has an optional metadata extension. It adds three functions:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #C678DD;">interface</span><span style="color: #E5C07B;"> IERC721Metadata</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> name</span><span>()</span><span style="color: #C678DD;"> external view returns</span><span> (</span><span style="color: #E5C07B;">string</span><span style="color: #C678DD;"> memory</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> symbol</span><span>()</span><span style="color: #C678DD;"> external view returns</span><span> (</span><span style="color: #E5C07B;">string</span><span style="color: #C678DD;"> memory</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">4</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> tokenURI</span><span>(</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> tokenId</span><span>)</span><span style="color: #C678DD;"> external view returns</span><span> (</span><span style="color: #E5C07B;">string</span><span style="color: #C678DD;"> memory</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">5</span><span>}</span></span></code></pre> <p><code>tokenURI</code> is the most important one. It returns a URL pointing to a JSON file that describes the token. The JSON follows a widely-adopted format:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="json"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span>{</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #E06C75;"> &quot;name&quot;</span><span>:</span><span style="color: #98C379;"> &quot;My NFT #123&quot;</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #E06C75;"> &quot;description&quot;</span><span>:</span><span style="color: #98C379;"> &quot;A unique digital item&quot;</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #E06C75;"> &quot;image&quot;</span><span>:</span><span style="color: #98C379;"> &quot;ipfs://QmX7...&quot;</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #E06C75;"> &quot;attributes&quot;</span><span>: [</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span> {</span><span style="color: #E06C75;"> &quot;trait_type&quot;</span><span>:</span><span style="color: #98C379;"> &quot;Background&quot;</span><span>,</span><span style="color: #E06C75;"> &quot;value&quot;</span><span>:</span><span style="color: #98C379;"> &quot;Blue&quot;</span><span> },</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span> {</span><span style="color: #E06C75;"> &quot;trait_type&quot;</span><span>:</span><span style="color: #98C379;"> &quot;Rarity&quot;</span><span>,</span><span style="color: #E06C75;"> &quot;value&quot;</span><span>:</span><span style="color: #98C379;"> &quot;Common&quot;</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span> ]</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span>}</span></span></code></pre> <p>Most projects store this JSON on IPFS rather than a centralized server. The smart contract stores only a hash or a base URI. The actual data lives off-chain.</p> <blockquote class="markdown-alert-important"> <p>The on-chain contract only stores a reference to the metadata, not the metadata itself. If the off-chain storage disappears, the metadata is gone. IPFS with pinning services is the standard approach for long-term availability.</p> </blockquote> <h2 id="safe-transfers">Safe Transfers</h2> <p>Beyond <code>transferFrom</code>, the standard defines safe transfer functions:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> safeTransferFrom</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> from</span><span>,</span><span style="color: #E5C07B;"> address</span><span style="color: #E06C75;font-style: italic;"> to</span><span>,</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> tokenId</span><span>)</span><span style="color: #C678DD;"> external</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> safeTransferFrom</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> from</span><span>,</span><span style="color: #E5C07B;"> address</span><span style="color: #E06C75;font-style: italic;"> to</span><span>,</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> tokenId</span><span>,</span><span style="color: #E5C07B;"> bytes</span><span style="color: #C678DD;"> calldata</span><span style="color: #E06C75;font-style: italic;"> data</span><span>)</span><span style="color: #C678DD;"> external</span><span>;</span></span></code></pre> <p>The difference from <code>transferFrom</code> is that these functions check whether the recipient can handle NFTs. If <code>to</code> is a contract, it must implement <code>IERC721Receiver</code>:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">interface</span><span style="color: #E5C07B;"> IERC721Receiver</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> onERC721Received</span><span>(</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #E5C07B;"> address</span><span style="color: #E06C75;font-style: italic;"> operator</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #E5C07B;"> address</span><span style="color: #E06C75;font-style: italic;"> from</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> tokenId</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #E5C07B;"> bytes</span><span style="color: #C678DD;"> calldata</span><span style="color: #E06C75;font-style: italic;"> data</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span> )</span><span style="color: #C678DD;"> external returns</span><span> (</span><span style="color: #E5C07B;">bytes4</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span>}</span></span></code></pre> <p>If the recipient contract does not implement this interface, the transfer reverts. This prevents tokens from getting permanently locked in contracts that have no way to move them.</p> <p>When in doubt, prefer <code>safeTransferFrom</code>. Use <code>transferFrom</code> only when you know the recipient can handle ERC-721 tokens.</p> <h2 id="required-events">Required Events</h2> <p>ERC-721 requires three events:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #C678DD;">event</span><span style="color: #E5C07B;"> Transfer</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #C678DD;"> indexed</span><span style="color: #E06C75;font-style: italic;"> from</span><span>, </span><span style="color: #E5C07B;">address</span><span style="color: #C678DD;"> indexed</span><span style="color: #E06C75;font-style: italic;"> to</span><span>, </span><span style="color: #E5C07B;">uint256</span><span style="color: #C678DD;"> indexed</span><span style="color: #E06C75;font-style: italic;"> tokenId</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #C678DD;">event</span><span style="color: #E5C07B;"> Approval</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #C678DD;"> indexed</span><span style="color: #E06C75;font-style: italic;"> owner</span><span>, </span><span style="color: #E5C07B;">address</span><span style="color: #C678DD;"> indexed</span><span style="color: #E06C75;font-style: italic;"> approved</span><span>, </span><span style="color: #E5C07B;">uint256</span><span style="color: #C678DD;"> indexed</span><span style="color: #E06C75;font-style: italic;"> tokenId</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span><span style="color: #C678DD;">event</span><span style="color: #E5C07B;"> ApprovalForAll</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #C678DD;"> indexed</span><span style="color: #E06C75;font-style: italic;"> owner</span><span>, </span><span style="color: #E5C07B;">address</span><span style="color: #C678DD;"> indexed</span><span style="color: #E06C75;font-style: italic;"> operator</span><span>, </span><span style="color: #E5C07B;">bool</span><span style="color: #E06C75;font-style: italic;"> approved</span><span>);</span></span></code></pre> <p>All three fields in <code>Transfer</code> are indexed, which means external applications can filter by sender, recipient, or token ID individually. Marketplaces and wallets rely on these events to track ownership history without querying every block.</p> <h2 id="the-optional-enumeration-extension">The Optional Enumeration Extension</h2> <p>The standard also defines an enumeration extension that lets you list tokens on-chain:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #C678DD;">interface</span><span style="color: #E5C07B;"> IERC721Enumerable</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> totalSupply</span><span>()</span><span style="color: #C678DD;"> external view returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> tokenByIndex</span><span>(</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> index</span><span>)</span><span style="color: #C678DD;"> external view returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">4</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> tokenOfOwnerByIndex</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> owner</span><span>,</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> index</span><span>)</span><span style="color: #C678DD;"> external view returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">5</span><span>}</span></span></code></pre> <p><code>tokenOfOwnerByIndex</code> lets you iterate over all tokens owned by a specific address. This is useful but expensive. It requires maintaining additional on-chain data structures, which increases gas costs on every mint and transfer. Many production contracts skip this extension and rely on off-chain indexers instead.</p> <h2 id="design-decisions-worth-thinking-about">Design Decisions Worth Thinking About</h2> <p><strong>Token ID strategy.</strong> Sequential IDs (1, 2, 3...) are simple and predictable. Random IDs prevent MEV bots from front-running mints to claim low-numbered tokens, which some collectors prefer. Pick based on whether rarity or simplicity matters more to your project.</p> <p><strong>On-chain vs off-chain data.</strong> Store as little as possible on-chain. Gas is expensive. Images, descriptions, and trait data belong off-chain. Only store what the contract logic actually needs.</p> <p><strong>Batch minting.</strong> Minting tokens one at a time is expensive. If your contract lets users mint multiple tokens, implement batch minting in a single transaction to reduce gas costs.</p> <blockquote class="markdown-alert-warning"> <p>Do not store large metadata blobs in contract storage. Every byte stored on-chain costs gas permanently. Even a moderately sized JSON object will make your contract expensive to deploy and interact with.</p> </blockquote> <h2 id="erc-721-vs-erc-20">ERC-721 vs ERC-20</h2> <p>The core difference is fungibility. ERC-20 tokens are fungible and divisible. ERC-721 tokens are non-fungible and indivisible.</p> <table><thead><tr><th>Property</th><th>ERC-20</th><th>ERC-721</th></tr></thead><tbody> <tr><td>Fungible</td><td>Yes</td><td>No</td></tr> <tr><td>Divisible</td><td>Yes</td><td>No</td></tr> <tr><td>Identified by</td><td>Amount</td><td>Token ID</td></tr> <tr><td>One owner per unit</td><td>No</td><td>Yes</td></tr> <tr><td>Approval granularity</td><td>Spending amount</td><td>Per-token or all-tokens</td></tr> </tbody></table> <p>The transfer calls reflect this difference directly:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #7F848E;font-style: italic;">// ERC-20: transfer an amount</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span>token.</span><span style="color: #61AFEF;">transfer</span><span>(recipient,</span><span style="color: #D19A66;"> 100</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">4</span><span style="color: #7F848E;font-style: italic;">// ERC-721: transfer a specific token</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">5</span><span>nft.</span><span style="color: #61AFEF;">transferFrom</span><span>(owner, recipient,</span><span style="color: #D19A66;"> 5</span><span>);</span></span></code></pre> <p>The approval model is also different:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #7F848E;font-style: italic;">// ERC-20: approve a spending limit</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span>token.</span><span style="color: #61AFEF;">approve</span><span>(spender,</span><span style="color: #D19A66;"> 1000</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #7F848E;font-style: italic;">// ERC-721: approve transfer of one specific token</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span>nft.</span><span style="color: #61AFEF;">approve</span><span>(spender,</span><span style="color: #D19A66;"> 5</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #7F848E;font-style: italic;">// ERC-721: approve an operator for all tokens</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span>nft.</span><span style="color: #61AFEF;">setApprovalForAll</span><span>(operator,</span><span style="color: #D19A66;"> true</span><span>);</span></span></code></pre> <p>Gas costs differ too. ERC-20 transfers update two balance values. ERC-721 transfers update an ownership mapping, update two balance counters, and clear an approval. ERC-721 transfers consistently cost more gas.</p> <h2 id="erc-721-vs-erc-1155">ERC-721 vs ERC-1155</h2> <p>ERC-1155 is a multi-token standard. One ERC-1155 contract can hold both fungible and non-fungible tokens at the same time. It also supports batch transfers in a single transaction:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #7F848E;font-style: italic;">// ERC-1155: transfer multiple token types at once</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #C678DD;">contract</span><span>.</span><span style="color: #61AFEF;">safeBatchTransferFrom</span><span>(from, to, [id1, id2, id3], [amount1, amount2, amount3], data);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">4</span><span style="color: #7F848E;font-style: italic;">// ERC-721: requires one transaction per token</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">5</span><span>nft.</span><span style="color: #61AFEF;">transferFrom</span><span>(from, to, tokenId1);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">6</span><span>nft.</span><span style="color: #61AFEF;">transferFrom</span><span>(from, to, tokenId2);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">7</span><span>nft.</span><span style="color: #61AFEF;">transferFrom</span><span>(from, to, tokenId3);</span></span></code></pre> <p>ERC-1155 is more gas-efficient when you need to move many tokens at once. It is also more flexible when a project needs both fungible items (currency, materials) and unique items (characters, land) in the same contract.</p> <p>The tradeoff is complexity. ERC-1155 is harder to implement correctly and has less uniform support across wallets and marketplaces than ERC-721.</p> <h2 id="when-to-use-each-standard">When to Use Each Standard</h2> <p>Pick ERC-20 when each unit is identical and you want divisibility. Currencies, governance tokens, and reward points belong here.</p> <p>Pick ERC-721 when each item is unique and indivisible. Digital art, collectibles, domain names, and certificates of ownership are the right fit.</p> <p>Pick ERC-1155 when you need both token types in the same system, or when batch operations matter for gas efficiency. Game inventories with weapons, currency, and unique characters are the typical use case.</p> <h2 id="security-basics">Security Basics</h2> <p>A few checks every ERC-721 contract should have:</p> <p>Verify a token exists before any operation:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #C678DD;">require</span><span>(owners[tokenId] !=</span><span style="color: #E5C07B;"> address</span><span>(</span><span style="color: #D19A66;">0</span><span>),</span><span style="color: #98C379;"> &quot;Token does not exist&quot;</span><span>);</span></span></code></pre> <p>Verify the caller has permission before any transfer:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #C678DD;">require</span><span>(</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #E5C07B;"> msg.sender</span><span> == owner ||</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span><span> tokenApprovals[tokenId] ==</span><span style="color: #E5C07B;"> msg.sender</span><span> ||</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">4</span><span> operatorApprovals[owner][</span><span style="color: #E5C07B;">msg.sender</span><span>],</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">5</span><span style="color: #98C379;"> &quot;Not authorized&quot;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">6</span><span>);</span></span></code></pre> <p>Block transfers to the zero address:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #C678DD;">require</span><span>(to !=</span><span style="color: #E5C07B;"> address</span><span>(</span><span style="color: #D19A66;">0</span><span>),</span><span style="color: #98C379;"> &quot;Transfer to zero address&quot;</span><span>);</span></span></code></pre> <p>Use reentrancy guards on any function that calls external contracts, including <code>safeTransferFrom</code>. The callback to <code>onERC721Received</code> is an external call, and the recipient contract can execute arbitrary code before your function returns.</p> <h2 id="summary">Summary</h2> <p>ERC-721 gives you a clear, well-adopted way to create unique digital assets on Ethereum. The standard handles ownership tracking, transfer permissions, and safe transfer callbacks. Metadata stays off-chain. The on-chain contract stores references, not data.</p> <p>It is not the most gas-efficient option and it lacks the batch capabilities of ERC-1155. But for projects where uniqueness is the core property, ERC-721 remains the default choice with the broadest support across tooling, wallets, and marketplaces.</p> 2025-11-17T00:00:00+00:00 2025-11-17T00:00:00+00:00 Akash Vaghela https://akash11.com/blog/contract-creation-in-solidity-create-create2-and-create3/ <p>Every contract deployed on Ethereum lives at an address. That address is not random. It is calculated deterministically from inputs that vary depending on which creation method you use.</p> <p>There are three main ways to deploy a contract: <code>CREATE</code>, <code>CREATE2</code>, and <code>CREATE3</code>. Each calculates the address differently, and that difference has real consequences for how you architect cross-chain systems, factory contracts, and upgradeable deployments. This post explains how each method works, what it costs, and when to use it.</p> <h2 id="create-the-original-method">CREATE: The Original Method</h2> <p><code>CREATE</code> has been part of Ethereum since genesis. The address of a contract deployed with <code>CREATE</code> is calculated like this:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="plain"><span class="giallo-l"><span>contract_address = keccak256(rlp([deployer_address, nonce]))[12:]</span></span></code></pre> <p>Two inputs determine the address:</p> <ol> <li>The deployer's address</li> <li>The deployer's nonce (total number of transactions sent from that address)</li> </ol> <p>Here is a minimal example using <code>CREATE</code> through Solidity's <code>new</code> keyword:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="Factory.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #7F848E;font-style: italic;">// SPDX-License-Identifier: MIT</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;">pragma</span><span style="color: #E06C75;"> solidity</span><span style="color: #D19A66;"> ^0.8.20</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> SimpleContract</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #E5C07B;"> uint256</span><span style="color: #C678DD;"> public</span><span> value </span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> 42</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Factory</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> deploy</span><span>()</span><span style="color: #C678DD;"> external returns</span><span> (</span><span style="color: #E5C07B;">address</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span> SimpleContract c </span><span style="color: #56B6C2;">=</span><span style="color: #C678DD;"> new</span><span style="color: #61AFEF;"> SimpleContract</span><span>();</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span style="color: #C678DD;"> return</span><span style="color: #E5C07B;"> address</span><span>(c);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span>}</span></span></code></pre> <p>Each time <code>deploy()</code> is called, the factory's nonce increments and the resulting address changes. You cannot predict the address in advance unless you know the exact nonce at the time of deployment.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="plain"><span class="giallo-l"><span>Deploy 1: nonce = 5 -&gt; address = 0xabc...</span></span> <span class="giallo-l"><span>Deploy 2: nonce = 6 -&gt; address = 0xdef...</span></span></code></pre> <p>This is fine for simple use cases. But it creates a problem the moment you need the same address on two different chains or want to redeploy a contract to a known location.</p> <p><strong>When to use CREATE:</strong></p> <ul> <li>Simple, single-chain deployments</li> <li>Address predictability is not a requirement</li> <li>You want the lowest possible deployment cost</li> </ul> <h2 id="create2-deterministic-deployment">CREATE2: Deterministic Deployment</h2> <p><code>CREATE2</code> was introduced in <a rel="noopener noreferrer external" target="_blank" href="https://eips.ethereum.org/EIPS/eip-1014">EIP-1014</a> to make contract addresses predictable before deployment. The formula changes to:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="plain"><span class="giallo-l"><span>contract_address = keccak256(0xff ++ deployer_address ++ salt ++ keccak256(bytecode))[12:]</span></span></code></pre> <p>Four inputs now determine the address:</p> <ol> <li><code>0xff</code>: a constant prefix to prevent collisions with <code>CREATE</code></li> <li>Deployer address</li> <li>Salt: a <code>bytes32</code> value you choose</li> <li><code>keccak256</code> of the contract's creation bytecode</li> </ol> <p>Because you control the salt and you know your own address and the bytecode, you can compute the address before the contract exists.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="Factory2.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #7F848E;font-style: italic;">// SPDX-License-Identifier: MIT</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;">pragma</span><span style="color: #E06C75;"> solidity</span><span style="color: #D19A66;"> ^0.8.20</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> SimpleContract</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #E5C07B;"> uint256</span><span style="color: #C678DD;"> public</span><span> value </span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> 42</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Factory</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> deploy</span><span>(</span><span style="color: #E5C07B;">bytes32</span><span style="color: #E06C75;font-style: italic;"> salt</span><span>)</span><span style="color: #C678DD;"> external returns</span><span> (</span><span style="color: #E5C07B;">address</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span> SimpleContract c </span><span style="color: #56B6C2;">=</span><span style="color: #C678DD;"> new</span><span> SimpleContract{salt: salt}();</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span style="color: #C678DD;"> return</span><span style="color: #E5C07B;"> address</span><span>(c);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> computeAddress</span><span>(</span><span style="color: #E5C07B;">bytes32</span><span style="color: #E06C75;font-style: italic;"> salt</span><span>)</span><span style="color: #C678DD;"> external view returns</span><span> (</span><span style="color: #E5C07B;">address</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span style="color: #E5C07B;"> bytes</span><span style="color: #C678DD;"> memory</span><span> bytecode </span><span style="color: #56B6C2;">=</span><span style="color: #E5C07B;"> type</span><span>(SimpleContract).creationCode;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span style="color: #E5C07B;"> bytes32</span><span> hash </span><span style="color: #56B6C2;">= keccak256</span><span>(</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">17</span><span style="color: #E5C07B;"> abi</span><span>.</span><span style="color: #61AFEF;">encodePacked</span><span>(</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">18</span><span style="color: #E5C07B;"> bytes1</span><span>(</span><span style="color: #D19A66;">0xff</span><span>),</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">19</span><span style="color: #E5C07B;"> address</span><span>(</span><span style="color: #E5C07B;">this</span><span>),</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">20</span><span> salt,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">21</span><span style="color: #56B6C2;"> keccak256</span><span>(bytecode)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">22</span><span> )</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">23</span><span> );</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">24</span><span style="color: #C678DD;"> return</span><span style="color: #E5C07B;"> address</span><span>(</span><span style="color: #E5C07B;">uint160</span><span>(</span><span style="color: #E5C07B;">uint256</span><span>(hash)));</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">25</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">26</span><span>}</span></span></code></pre> <p><code>computeAddress</code> returns the exact address where the contract will land before you deploy it. This unlocks a pattern called counterfactual instantiation: other contracts can reference or send funds to an address before the contract at that address exists.</p> <p><code>CREATE2</code> also allows redeployment to the same address. If you deploy a contract, call <code>SELFDESTRUCT</code> on it, then redeploy with the same salt and same bytecode, it lands at the same address again.</p> <blockquote class="markdown-alert-warning"> <p><code>SELFDESTRUCT</code> behavior is subject to EIP proposals that may deprecate or restrict it in future network upgrades. Do not build critical systems that depend on <code>SELFDESTRUCT</code> and <code>CREATE2</code> redeployment without tracking EIP-6780 and related proposals.</p> </blockquote> <p>The limitation of <code>CREATE2</code> is that the bytecode is part of the address calculation. If you want to deploy different code to the same address on different chains, you cannot do it with <code>CREATE2</code> alone.</p> <p><strong>When to use CREATE2:</strong></p> <ul> <li>You need to predict a contract's address before deploying it</li> <li>You want the same address across chains, and you can guarantee identical bytecode</li> <li>You are building counterfactual systems (payment channels, state channels, intent-based protocols)</li> </ul> <h2 id="create3-address-independent-of-bytecode">CREATE3: Address Independent of Bytecode</h2> <p><code>CREATE3</code> is not a native EVM opcode. It is a pattern that combines <code>CREATE2</code> and <code>CREATE</code> to separate address determination from contract bytecode. The result: the same salt produces the same address regardless of what code you deploy.</p> <p>The mechanism works in two steps:</p> <ol> <li>A factory deploys a minimal proxy using <code>CREATE2</code> with your chosen salt. This gives the proxy a deterministic address.</li> <li>The proxy immediately deploys the actual contract using <code>CREATE</code>. Since the proxy is freshly created, its nonce is always <code>1</code>.</li> </ol> <p>Because the proxy address is determined by the salt alone (not the bytecode of the final contract), and the proxy's nonce is always <code>1</code>, the final contract address depends only on your salt.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="plain"><span class="giallo-l"><span>final_address = keccak256(rlp([proxy_address, 1]))[12:]</span></span></code></pre> <p>Here is a simplified implementation:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="Factory3.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #7F848E;font-style: italic;">// SPDX-License-Identifier: MIT</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;">pragma</span><span style="color: #E06C75;"> solidity</span><span style="color: #D19A66;"> ^0.8.20</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Proxy</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> deploy</span><span>(</span><span style="color: #E5C07B;">bytes</span><span style="color: #C678DD;"> memory</span><span style="color: #E06C75;font-style: italic;"> code</span><span>)</span><span style="color: #C678DD;"> external returns</span><span> (</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> addr</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #C678DD;"> assembly</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span> addr </span><span style="color: #56B6C2;">:=</span><span style="color: #61AFEF;"> create</span><span>(</span><span style="color: #D19A66;">0</span><span>,</span><span style="color: #61AFEF;"> add</span><span>(code,</span><span style="color: #D19A66;"> 0x20</span><span>),</span><span style="color: #61AFEF;"> mload</span><span>(code))</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #C678DD;"> require</span><span>(addr !=</span><span style="color: #E5C07B;"> address</span><span>(</span><span style="color: #D19A66;">0</span><span>),</span><span style="color: #98C379;"> &quot;Deployment failed&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Factory</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> deploy</span><span>(</span><span style="color: #E5C07B;">bytes32</span><span style="color: #E06C75;font-style: italic;"> salt</span><span>,</span><span style="color: #E5C07B;"> bytes</span><span style="color: #C678DD;"> memory</span><span style="color: #E06C75;font-style: italic;"> code</span><span>)</span><span style="color: #C678DD;"> external returns</span><span> (</span><span style="color: #E5C07B;">address</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span style="color: #7F848E;font-style: italic;"> // Step 1: deploy proxy deterministically with CREATE2</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span style="color: #E5C07B;"> address</span><span> proxy </span><span style="color: #56B6C2;">=</span><span style="color: #E5C07B;"> address</span><span>(</span><span style="color: #C678DD;">new</span><span> Proxy{salt: salt}());</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">17</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">18</span><span style="color: #7F848E;font-style: italic;"> // Step 2: proxy deploys actual contract with CREATE</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">19</span><span style="color: #C678DD;"> return</span><span style="color: #61AFEF;"> Proxy</span><span>(proxy).</span><span style="color: #61AFEF;">deploy</span><span>(code);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">20</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">21</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">22</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> addressOf</span><span>(</span><span style="color: #E5C07B;">bytes32</span><span style="color: #E06C75;font-style: italic;"> salt</span><span>)</span><span style="color: #C678DD;"> external view returns</span><span> (</span><span style="color: #E5C07B;">address</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">23</span><span style="color: #7F848E;font-style: italic;"> // Predict proxy address using CREATE2 formula</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">24</span><span style="color: #E5C07B;"> bytes32</span><span> proxyHash </span><span style="color: #56B6C2;">= keccak256</span><span>(</span><span style="color: #E5C07B;">type</span><span>(Proxy).creationCode);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">25</span><span style="color: #E5C07B;"> address</span><span> proxy </span><span style="color: #56B6C2;">=</span><span style="color: #E5C07B;"> address</span><span>(</span><span style="color: #E5C07B;">uint160</span><span>(</span><span style="color: #E5C07B;">uint256</span><span>(</span><span style="color: #56B6C2;">keccak256</span><span>(</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">26</span><span style="color: #E5C07B;"> abi</span><span>.</span><span style="color: #61AFEF;">encodePacked</span><span>(</span><span style="color: #E5C07B;">bytes1</span><span>(</span><span style="color: #D19A66;">0xff</span><span>),</span><span style="color: #E5C07B;"> address</span><span>(</span><span style="color: #E5C07B;">this</span><span>), salt, proxyHash)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">27</span><span> ))));</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">28</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">29</span><span style="color: #7F848E;font-style: italic;"> // Proxy nonce is always 1 for first deployment</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">30</span><span style="color: #C678DD;"> return</span><span style="color: #E5C07B;"> address</span><span>(</span><span style="color: #E5C07B;">uint160</span><span>(</span><span style="color: #E5C07B;">uint256</span><span>(</span><span style="color: #56B6C2;">keccak256</span><span>(</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">31</span><span style="color: #E5C07B;"> abi</span><span>.</span><span style="color: #61AFEF;">encodePacked</span><span>(</span><span style="color: #E5C07B;">bytes1</span><span>(</span><span style="color: #D19A66;">0xd6</span><span>),</span><span style="color: #E5C07B;"> bytes1</span><span>(</span><span style="color: #D19A66;">0x94</span><span>), proxy,</span><span style="color: #E5C07B;"> bytes1</span><span>(</span><span style="color: #D19A66;">0x01</span><span>))</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">32</span><span> ))));</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">33</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">34</span><span>}</span></span></code></pre> <blockquote class="markdown-alert-note"> <p>In production, use an audited <code>CREATE3</code> library such as <a rel="noopener noreferrer external" target="_blank" href="https://github.com/Vectorized/solady/blob/main/src/utils/CREATE3.sol">solady's <code>CREATE3</code></a> or <a rel="noopener noreferrer external" target="_blank" href="https://github.com/transmissions11/solmate/blob/main/src/utils/CREATE3.sol">transmissions11/solmate</a> rather than rolling your own. The proxy bytecode must be exact and stable.</p> </blockquote> <p>The cost of <code>CREATE3</code> is higher than both <code>CREATE</code> and <code>CREATE2</code> because two deployments happen for every contract: one for the proxy, one for the actual contract.</p> <p><strong>When to use CREATE3:</strong></p> <ul> <li>You need the same address across chains and you cannot guarantee identical bytecode (different compiler versions, different constructor arguments encoded into bytecode, intentional code differences)</li> <li>You want a clean address registry where a single salt always resolves to the same address regardless of what is deployed there</li> </ul> <h2 id="side-by-side-comparison">Side-by-Side Comparison</h2> <table><thead><tr><th></th><th>CREATE</th><th>CREATE2</th><th>CREATE3</th></tr></thead><tbody> <tr><td>Address depends on</td><td><code>deployer</code>, <code>nonce</code></td><td><code>deployer</code>, <code>salt</code>, <code>bytecode</code></td><td><code>deployer</code>, <code>salt</code> only</td></tr> <tr><td>Predictable before deploy</td><td>No</td><td>Yes</td><td>Yes</td></tr> <tr><td>Same address across chains</td><td>No</td><td>Yes, if bytecode matches</td><td>Yes, always</td></tr> <tr><td>Can redeploy to same address</td><td>No</td><td>Yes (requires SELFDESTRUCT)</td><td>No (proxy nonce increments)</td></tr> <tr><td>Gas cost</td><td>Lowest</td><td>Low</td><td>Higher (two deployments)</td></tr> <tr><td>Native EVM support</td><td>Yes</td><td>Yes</td><td>No (pattern only)</td></tr> </tbody></table> <h2 id="cross-chain-address-example">Cross-Chain Address Example</h2> <p>This is the scenario where the choice matters most. You are deploying the same protocol to Ethereum and Arbitrum.</p> <p>With <code>CREATE</code>, the nonce on each chain may differ. You get different addresses.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="plain"><span class="giallo-l"><span>Ethereum: deployer nonce = 5 -&gt; 0xabc...</span></span> <span class="giallo-l"><span>Arbitrum: deployer nonce = 3 -&gt; 0xdef...</span></span></code></pre> <p>With <code>CREATE2</code>, same salt and same bytecode means same address. But if your bytecode differs at all, the address changes.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="plain"><span class="giallo-l"><span>Ethereum: salt=X, bytecode=Y -&gt; 0x123...</span></span> <span class="giallo-l"><span>Arbitrum: salt=X, bytecode=Y -&gt; 0x123... (same)</span></span> <span class="giallo-l"><span>Arbitrum: salt=X, bytecode=Z -&gt; 0x456... (different!)</span></span></code></pre> <p>With <code>CREATE3</code>, the bytecode is irrelevant to the address. Only the salt and the factory address matter.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="plain"><span class="giallo-l"><span>Ethereum: salt=X -&gt; 0x789... (any bytecode)</span></span> <span class="giallo-l"><span>Arbitrum: salt=X -&gt; 0x789... (any bytecode)</span></span></code></pre> <p>This is why protocols that deploy across many chains often build their own <code>CREATE3</code> factory, deployed to the same address on each chain using <code>CREATE2</code>, then use that factory for all subsequent deployments.</p> <h2 id="choosing-the-right-method">Choosing the Right Method</h2> <p>The decision comes down to two questions: do you need predictability, and do you need bytecode independence?</p> <p>If predictability is not needed, use <code>CREATE</code>. It is the cheapest and simplest option.</p> <p>If you need predictability and can guarantee identical bytecode across deployments, use <code>CREATE2</code>. It is cheaper than <code>CREATE3</code> and natively supported by the EVM.</p> <p>If you need predictability but cannot guarantee identical bytecode, use <code>CREATE3</code>. Accept the extra gas cost in exchange for a stable address registry that is independent of your implementation details.</p> 2025-11-09T00:00:00+00:00 2025-11-09T00:00:00+00:00 Akash Vaghela https://akash11.com/blog/msg-sender-vs-txorigin-in-solidity/ <p>Solidity gives you two built-in variables to identify who is calling your contract: <code>msg.sender</code> and <code>tx.origin</code>. They look similar, but they track different things. Picking the wrong one for access control is one of the most common and exploitable mistakes in Solidity code.</p> <p>This post explains what each variable does, how they differ in a multi-contract call chain, and why <code>tx.origin</code> is dangerous for authentication.</p> <h2 id="what-each-variable-tracks">What Each Variable Tracks</h2> <p><code>msg.sender</code> is the <strong>immediate caller</strong> of the current function. If a user calls your contract directly, <code>msg.sender</code> is the user's address. If another contract calls your contract, <code>msg.sender</code> is that contract's address. It changes at every step in the call chain.</p> <p><code>tx.origin</code> is the <strong>original transaction signer</strong>. It always points to the externally owned account (EOA) that signed and submitted the transaction, no matter how many contracts are involved in the call chain. It never changes within a transaction.</p> <h2 id="how-the-call-chain-changes-msg-sender">How the Call Chain Changes msg.sender</h2> <p>Consider this call sequence:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="plain"><span class="giallo-l"><span>User (0xUser)</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span> | calls</span></span> <span class="giallo-l"><span> v</span></span> <span class="giallo-l"><span>Contract A</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span> | calls</span></span> <span class="giallo-l"><span> v</span></span> <span class="giallo-l"><span>Contract B</span></span></code></pre> <p>Inside <code>Contract B</code>, the two variables resolve to different addresses:</p> <ul> <li><code>msg.sender</code> = address of <code>Contract A</code></li> <li><code>tx.origin</code> = <code>0xUser</code> (the original EOA)</li> </ul> <p>This difference is subtle, but it has serious security consequences.</p> <p>Here is a minimal contract that records both values:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="CallerInfo.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> CallerInfo</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #E5C07B;"> address</span><span style="color: #C678DD;"> public</span><span> lastSender;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #E5C07B;"> address</span><span style="color: #C678DD;"> public</span><span> lastOrigin;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> recordCaller</span><span>()</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span> lastSender </span><span style="color: #56B6C2;">=</span><span style="color: #E5C07B;"> msg.sender</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span> lastOrigin </span><span style="color: #56B6C2;">=</span><span style="color: #E5C07B;"> tx</span><span>.origin;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Intermediary</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> callThroughMe</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> target</span><span>)</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span style="color: #61AFEF;"> CallerInfo</span><span>(target).</span><span style="color: #61AFEF;">recordCaller</span><span>();</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span>}</span></span></code></pre> <p>If a user at <code>0xUser</code> calls <code>Intermediary.callThroughMe()</code>, which then calls <code>CallerInfo.recordCaller()</code>:</p> <ul> <li><code>lastSender</code> will hold the address of the <code>Intermediary</code> contract</li> <li><code>lastOrigin</code> will hold <code>0xUser</code></li> </ul> <h2 id="the-security-problem-with-tx-origin">The Security Problem with tx.origin</h2> <p>Using <code>tx.origin</code> for authentication creates a phishing vulnerability. Any contract that tricks the real owner into calling it can drain funds from your wallet.</p> <p>Here is a vulnerable wallet:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="Wallet.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Wallet</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #E5C07B;"> address</span><span style="color: #C678DD;"> public</span><span> owner;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;"> constructor</span><span>() {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span> owner </span><span style="color: #56B6C2;">=</span><span style="color: #E5C07B;"> msg.sender</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> transfer</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> to</span><span>,</span><span style="color: #E5C07B;"> uint</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>)</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l" style="background-color: #2C313C;"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #C678DD;"> require</span><span>(</span><span style="color: #E5C07B;">tx</span><span>.origin == owner,</span><span style="color: #98C379;"> &quot;Not owner&quot;</span><span>);</span><span style="color: #7F848E;font-style: italic;"> // vulnerable</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #C678DD;"> payable</span><span>(to).</span><span style="color: #61AFEF;">transfer</span><span>(amount);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span>}</span></span></code></pre> <p>An attacker deploys this malicious contract:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="Attack.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Attack</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span> Wallet </span><span style="color: #C678DD;">public</span><span> wallet;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #E5C07B;"> address</span><span style="color: #C678DD;"> public</span><span> attacker;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #C678DD;"> constructor</span><span>(</span><span style="color: #E5C07B;">address</span><span style="font-style: italic;"> _wallet</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span> wallet </span><span style="color: #56B6C2;">=</span><span style="color: #61AFEF;"> Wallet</span><span>(_wallet);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span> attacker </span><span style="color: #56B6C2;">=</span><span style="color: #E5C07B;"> msg.sender</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> attack</span><span>()</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span style="color: #7F848E;font-style: italic;"> // Calls the wallet on behalf of whoever calls this function</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span> wallet.</span><span style="color: #61AFEF;">transfer</span><span>(attacker,</span><span style="color: #E5C07B;"> address</span><span>(wallet).balance);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span>}</span></span></code></pre> <p>The attack works like this:</p> <ol> <li>The attacker shares the <code>Attack</code> contract with the wallet owner (through a phishing site, a malicious airdrop, etc.)</li> <li>The owner calls <code>Attack.attack()</code>, thinking they are interacting with some other protocol</li> <li><code>Attack.attack()</code> calls <code>Wallet.transfer()</code></li> <li>Inside <code>Wallet.transfer()</code>, the check <code>tx.origin == owner</code> passes because the owner did sign the original transaction</li> <li>Funds are sent to the attacker's address</li> </ol> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="plain"><span class="giallo-l"><span>Owner (tx.origin = owner)</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span> | tricked into calling</span></span> <span class="giallo-l"><span> v</span></span> <span class="giallo-l"><span>Attack.attack()</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span> | calls</span></span> <span class="giallo-l"><span> v</span></span> <span class="giallo-l"><span>Wallet.transfer()</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span> | require(tx.origin == owner) passes</span></span> <span class="giallo-l"><span> v</span></span> <span class="giallo-l"><span>Funds drained</span></span></code></pre> <p>The wallet never knew the owner did not directly authorize this transfer. It only checked who signed the transaction, not who actually called the function.</p> <blockquote class="markdown-alert-warning"> <p>Never use <code>tx.origin</code> as the sole check for ownership or authorization. Any intermediate contract in the call chain can exploit it.</p> </blockquote> <h2 id="the-fix-use-msg-sender">The Fix: Use msg.sender</h2> <p>Replace <code>tx.origin</code> with <code>msg.sender</code> in the access control check:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="SafeWallet.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> SafeWallet</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #E5C07B;"> address</span><span style="color: #C678DD;"> public</span><span> owner;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;"> constructor</span><span>() {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span> owner </span><span style="color: #56B6C2;">=</span><span style="color: #E5C07B;"> msg.sender</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> transfer</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> to</span><span>,</span><span style="color: #E5C07B;"> uint</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>)</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l" style="background-color: #2C313C;"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #C678DD;"> require</span><span>(</span><span style="color: #E5C07B;">msg.sender</span><span> == owner,</span><span style="color: #98C379;"> &quot;Not owner&quot;</span><span>);</span><span style="color: #7F848E;font-style: italic;"> // safe</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #C678DD;"> payable</span><span>(to).</span><span style="color: #61AFEF;">transfer</span><span>(amount);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span>}</span></span></code></pre> <p>The same attack now fails:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="plain"><span class="giallo-l"><span>Owner</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span> | calls</span></span> <span class="giallo-l"><span> v</span></span> <span class="giallo-l"><span>Attack.attack()</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span> | calls</span></span> <span class="giallo-l"><span> v</span></span> <span class="giallo-l"><span>SafeWallet.transfer()</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span> | require(msg.sender == owner) fails</span></span> <span class="giallo-l"><span> | (msg.sender is the Attack contract, not the owner)</span></span> <span class="giallo-l"><span> v</span></span> <span class="giallo-l"><span>Transaction reverts</span></span></code></pre> <p>Because <code>msg.sender</code> is the <code>Attack</code> contract's address, not the owner's address, the require check rejects the call.</p> <h2 id="when-tx-origin-is-acceptable">When tx.origin Is Acceptable</h2> <p>There are narrow, non-security use cases where <code>tx.origin</code> is useful:</p> <p><strong>Gas tracking in relay contracts.</strong> If you are building a meta-transaction relay, you might want to track gas usage by the original end user rather than the relay itself:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="GasRelay.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> GasRelay</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;"> mapping</span><span>(</span><span style="color: #E5C07B;">address</span><span> =&gt;</span><span style="color: #E5C07B;"> uint</span><span>)</span><span style="color: #C678DD;"> public</span><span> userGasSpent;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> relayCall</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> target</span><span>,</span><span style="color: #E5C07B;"> bytes</span><span style="color: #C678DD;"> calldata</span><span style="color: #E06C75;font-style: italic;"> data</span><span>)</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #E5C07B;"> uint</span><span> gasBefore </span><span style="color: #56B6C2;">=</span><span style="color: #E5C07B;"> gasleft</span><span>();</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span> (</span><span style="color: #E5C07B;">bool</span><span> success,)</span><span style="color: #56B6C2;"> =</span><span> target.</span><span style="color: #61AFEF;">call</span><span>(data);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #C678DD;"> require</span><span>(success,</span><span style="color: #98C379;"> &quot;Call failed&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #7F848E;font-style: italic;"> // Track gas by the original user, not this relay contract</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span> userGasSpent[</span><span style="color: #E5C07B;">tx</span><span>.origin]</span><span style="color: #56B6C2;"> +=</span><span> gasBefore </span><span style="color: #56B6C2;">-</span><span style="color: #E5C07B;"> gasleft</span><span>();</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span>}</span></span></code></pre> <p>Here <code>tx.origin</code> is used only for bookkeeping. The actual access control inside <code>target</code> still uses <code>msg.sender</code>.</p> <p><strong>Analytics and event logging.</strong> If you want to emit an event that records who ultimately initiated a batch of calls, <code>tx.origin</code> lets you capture the end user's address.</p> <p>In both cases, <code>tx.origin</code> is supplemental information, not a security gate.</p> <h2 id="quick-reference">Quick Reference</h2> <table><thead><tr><th>Use case</th><th>Use</th></tr></thead><tbody> <tr><td>Ownership checks</td><td><code>msg.sender</code></td></tr> <tr><td>Access control and permissions</td><td><code>msg.sender</code></td></tr> <tr><td>Transferring funds or tokens</td><td><code>msg.sender</code></td></tr> <tr><td>Any security-critical check</td><td><code>msg.sender</code></td></tr> <tr><td>Logging the originating EOA</td><td><code>tx.origin</code></td></tr> <tr><td>Gas tracking in relays</td><td><code>tx.origin</code></td></tr> <tr><td>Meta-transaction patterns (non-auth)</td><td><code>tx.origin</code></td></tr> </tbody></table> <h2 id="summary">Summary</h2> <p><code>msg.sender</code> reflects the direct caller of your function. <code>tx.origin</code> reflects the EOA that started the entire transaction. For any access control or ownership check, always use <code>msg.sender</code>. Using <code>tx.origin</code> for authentication lets a malicious contract impersonate the real user simply by getting them to call it, even once. Reserve <code>tx.origin</code> for analytics or tracking purposes where security is not at stake.</p> 2025-11-08T00:00:00+00:00 2025-11-08T00:00:00+00:00 Akash Vaghela https://akash11.com/blog/call-and-delegatecall-in-solidity/ <p>Solidity gives you regular function calls for most contract-to-contract interactions. But two low-level functions, <code>call</code> and <code>delegatecall</code>, let you go further. They bypass the usual function call safety checks and give you direct control over how code runs and where state is stored.</p> <p>This post explains what each function does, how they differ, when to use them, and what can go wrong.</p> <h2 id="what-call-does">What call Does</h2> <p><code>call</code> is a low-level function that triggers a function on another contract. The code runs in the target contract's context. That means the target contract's storage gets modified, the target's address is used as <code>this</code>, and any Ether sent goes to the target's balance.</p> <p>Basic syntax:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span>(</span><span style="color: #E5C07B;">bool</span><span> success,</span><span style="color: #E5C07B;"> bytes</span><span style="color: #C678DD;"> memory</span><span> data)</span><span style="color: #56B6C2;"> =</span><span> targetAddress.call{value: amount}(</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #E5C07B;"> abi</span><span>.</span><span style="color: #61AFEF;">encodeWithSignature</span><span>(</span><span style="color: #98C379;">&quot;functionName(uint256)&quot;</span><span>, argument)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span><span>);</span></span></code></pre> <p>The function returns two values. <code>success</code> is <code>true</code> if the call worked and <code>false</code> if it failed. <code>data</code> holds the return value from the called function.</p> <p>Here is a working example:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="call-example.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Receiver</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #E5C07B;"> uint256</span><span style="color: #C678DD;"> public</span><span> value;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> setValue</span><span>(</span><span style="color: #E5C07B;">uint256</span><span style="font-style: italic;"> _value</span><span>)</span><span style="color: #C678DD;"> public payable</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span> value </span><span style="color: #56B6C2;">=</span><span> _value;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Caller</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> callSetValue</span><span>(</span><span style="color: #E5C07B;">address</span><span style="font-style: italic;"> _receiver</span><span>,</span><span style="color: #E5C07B;"> uint256</span><span style="font-style: italic;"> _value</span><span>)</span><span style="color: #C678DD;"> public payable</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span> (</span><span style="color: #E5C07B;">bool</span><span> success, )</span><span style="color: #56B6C2;"> =</span><span> _receiver.call{value:</span><span style="color: #E5C07B;"> msg</span><span>.value}(</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span style="color: #E5C07B;"> abi</span><span>.</span><span style="color: #61AFEF;">encodeWithSignature</span><span>(</span><span style="color: #98C379;">&quot;setValue(uint256)&quot;</span><span>, _value)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span> );</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span style="color: #C678DD;"> require</span><span>(success,</span><span style="color: #98C379;"> &quot;Call failed&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span>}</span></span></code></pre> <p>When <code>Caller</code> uses <code>call</code> to trigger <code>setValue</code>, the <code>value</code> variable inside <code>Receiver</code> gets updated. The Ether sent goes to <code>Receiver</code>'s balance. <code>Caller</code> is not affected.</p> <h3 id="when-to-use-call">When to Use call</h3> <p>Use <code>call</code> in these situations:</p> <ul> <li>Sending Ether to an address. It is the recommended method since <code>transfer</code> and <code>send</code> have a fixed gas stipend that can cause failures.</li> <li>Interacting with a contract you do not have the interface or ABI for.</li> <li>Building generic contract interactions where you need to forward all remaining gas.</li> <li>Implementing proxy patterns.</li> </ul> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="send-ether.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> SendEther</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> sendViaCall</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> payable</span><span style="font-style: italic;"> _to</span><span>)</span><span style="color: #C678DD;"> public payable</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span><span> (</span><span style="color: #E5C07B;">bool</span><span> sent, )</span><span style="color: #56B6C2;"> =</span><span> _to.call{value:</span><span style="color: #E5C07B;"> msg</span><span>.value}(</span><span style="color: #98C379;">&quot;&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">4</span><span style="color: #C678DD;"> require</span><span>(sent,</span><span style="color: #98C379;"> &quot;Failed to send Ether&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">5</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">6</span><span>}</span></span></code></pre> <blockquote class="markdown-alert-warning"> <p><code>call</code> does not revert automatically on failure. Always check the <code>success</code> boolean and handle failures explicitly. Ignoring it is a common source of bugs.</p> </blockquote> <h2 id="what-delegatecall-does">What delegatecall Does</h2> <p><code>delegatecall</code> runs another contract's code inside your contract's context. The target contract provides the logic, but your contract's storage, address, and balance are used. The <code>msg.sender</code> and <code>msg.value</code> from the original transaction are also preserved.</p> <p>This is the key distinction: <code>call</code> runs code in the target's world, while <code>delegatecall</code> borrows the target's code and runs it in your world.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="plain"><span class="giallo-l"><span>call:</span></span> <span class="giallo-l"><span> Caller --&gt; Target</span></span> <span class="giallo-l"><span> Target&#39;s storage is modified</span></span> <span class="giallo-l"><span> Target&#39;s address is `this`</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>delegatecall:</span></span> <span class="giallo-l"><span> Caller --&gt; borrows Target&#39;s code</span></span> <span class="giallo-l"><span> Caller&#39;s storage is modified</span></span> <span class="giallo-l"><span> Caller&#39;s address is `this`</span></span></code></pre> <p>Here is a basic example:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="delegatecall-example.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Logic</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #E5C07B;"> uint256</span><span style="color: #C678DD;"> public</span><span> number;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> setNumber</span><span>(</span><span style="color: #E5C07B;">uint256</span><span style="font-style: italic;"> _number</span><span>)</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span> number </span><span style="color: #56B6C2;">=</span><span> _number;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Storage</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #E5C07B;"> uint256</span><span style="color: #C678DD;"> public</span><span> number;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> delegateSetNumber</span><span>(</span><span style="color: #E5C07B;">address</span><span style="font-style: italic;"> _logic</span><span>,</span><span style="color: #E5C07B;"> uint256</span><span style="font-style: italic;"> _number</span><span>)</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span> (</span><span style="color: #E5C07B;">bool</span><span> success, )</span><span style="color: #56B6C2;"> =</span><span> _logic.</span><span style="color: #61AFEF;">delegatecall</span><span>(</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span style="color: #E5C07B;"> abi</span><span>.</span><span style="color: #61AFEF;">encodeWithSignature</span><span>(</span><span style="color: #98C379;">&quot;setNumber(uint256)&quot;</span><span>, _number)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span> );</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span style="color: #C678DD;"> require</span><span>(success,</span><span style="color: #98C379;"> &quot;Delegatecall failed&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">17</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">18</span><span>}</span></span></code></pre> <p>When <code>Storage</code> calls <code>delegateSetNumber</code>, it runs <code>Logic.setNumber</code> using <code>delegatecall</code>. The <code>number</code> variable in <code>Storage</code> gets updated, not the one in <code>Logic</code>. The code from <code>Logic</code> runs, but it operates on <code>Storage</code>'s data.</p> <h3 id="storage-layout-must-match">Storage Layout Must Match</h3> <p>This is the most important rule when using <code>delegatecall</code>. The calling contract and the logic contract must declare their state variables in the same order.</p> <p>When <code>delegatecall</code> writes to <code>number</code>, it writes to slot 0 in storage. It does not know the variable name. It only knows the slot number.</p> <p>Matching layout (correct):</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="matching-layout.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> A</span><span> {</span></span> <span class="giallo-l" style="background-color: #2C313C;"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #E5C07B;"> uint256</span><span style="color: #C678DD;"> public</span><span> num;</span><span style="color: #7F848E;font-style: italic;"> // slot 0</span></span> <span class="giallo-l" style="background-color: #2C313C;"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #E5C07B;"> address</span><span style="color: #C678DD;"> public</span><span> sender;</span><span style="color: #7F848E;font-style: italic;"> // slot 1</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> B</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #E5C07B;"> uint256</span><span style="color: #C678DD;"> public</span><span> num;</span><span style="color: #7F848E;font-style: italic;"> // slot 0</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #E5C07B;"> address</span><span style="color: #C678DD;"> public</span><span> sender;</span><span style="color: #7F848E;font-style: italic;"> // slot 1</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> setVars</span><span>(</span><span style="color: #E5C07B;">uint256</span><span style="font-style: italic;"> _num</span><span>)</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span> num </span><span style="color: #56B6C2;">=</span><span> _num;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span> sender </span><span style="color: #56B6C2;">=</span><span style="color: #E5C07B;"> msg.sender</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span>}</span></span></code></pre> <p>Mismatched layout (dangerous):</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="mismatched-layout.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> A</span><span> {</span></span> <span class="giallo-l" style="background-color: #2C313C;"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #E5C07B;"> address</span><span style="color: #C678DD;"> public</span><span> owner;</span><span style="color: #7F848E;font-style: italic;"> // slot 0</span></span> <span class="giallo-l" style="background-color: #2C313C;"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #E5C07B;"> uint256</span><span style="color: #C678DD;"> public</span><span> value;</span><span style="color: #7F848E;font-style: italic;"> // slot 1</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> B</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #E5C07B;"> uint256</span><span style="color: #C678DD;"> public</span><span> value;</span><span style="color: #7F848E;font-style: italic;"> // slot 0 -- mismatched</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #E5C07B;"> address</span><span style="color: #C678DD;"> public</span><span> owner;</span><span style="color: #7F848E;font-style: italic;"> // slot 1 -- mismatched</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span>}</span></span></code></pre> <p>If you use <code>delegatecall</code> between <code>A</code> and <code>B</code> in the mismatched example, writing to <code>value</code> in the logic contract writes to slot 0 in <code>A</code>. That overwrites <code>owner</code>. Your storage gets corrupted silently.</p> <blockquote class="markdown-alert-caution"> <p>Storage layout mismatch with <code>delegatecall</code> does not throw an error. The transaction succeeds, but the wrong variables get overwritten. This is one of the most dangerous bugs in Solidity.</p> </blockquote> <h2 id="the-proxy-pattern">The Proxy Pattern</h2> <p>The most common use of <code>delegatecall</code> in production is the upgradeable proxy pattern. The idea: users interact with a proxy contract, but the actual logic lives in a separate implementation contract. You can upgrade the contract by pointing the proxy to a new implementation, without changing the address users interact with.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="proxy.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Proxy</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #E5C07B;"> address</span><span style="color: #C678DD;"> public</span><span> implementation;</span><span style="color: #7F848E;font-style: italic;"> // slot 0</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #E5C07B;"> uint256</span><span style="color: #C678DD;"> public</span><span> value;</span><span style="color: #7F848E;font-style: italic;"> // slot 1</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #C678DD;"> constructor</span><span>(</span><span style="color: #E5C07B;">address</span><span style="font-style: italic;"> _implementation</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span> implementation </span><span style="color: #56B6C2;">=</span><span> _implementation;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #61AFEF;"> fallback</span><span>()</span><span style="color: #C678DD;"> external payable</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #E5C07B;"> address</span><span> impl </span><span style="color: #56B6C2;">=</span><span> implementation;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span style="color: #C678DD;"> assembly</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span style="color: #61AFEF;"> calldatacopy</span><span>(</span><span style="color: #D19A66;">0</span><span>,</span><span style="color: #D19A66;"> 0</span><span>,</span><span style="color: #61AFEF;"> calldatasize</span><span>())</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span style="color: #C678DD;"> let</span><span> result </span><span style="color: #56B6C2;">:=</span><span style="color: #61AFEF;"> delegatecall</span><span>(</span><span style="color: #61AFEF;">gas</span><span>(), impl,</span><span style="color: #D19A66;"> 0</span><span>,</span><span style="color: #61AFEF;"> calldatasize</span><span>(),</span><span style="color: #D19A66;"> 0</span><span>,</span><span style="color: #D19A66;"> 0</span><span>)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span style="color: #61AFEF;"> returndatacopy</span><span>(</span><span style="color: #D19A66;">0</span><span>,</span><span style="color: #D19A66;"> 0</span><span>,</span><span style="color: #61AFEF;"> returndatasize</span><span>())</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span> switch result</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span> case </span><span style="color: #D19A66;">0</span><span> {</span><span style="color: #C678DD;"> revert</span><span>(</span><span style="color: #D19A66;">0</span><span>,</span><span style="color: #61AFEF;"> returndatasize</span><span>()) }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">17</span><span> default {</span><span style="color: #C678DD;"> return</span><span>(</span><span style="color: #D19A66;">0</span><span>,</span><span style="color: #61AFEF;"> returndatasize</span><span>()) }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">18</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">19</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">20</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">21</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">22</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Implementation</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">23</span><span style="color: #E5C07B;"> address</span><span style="color: #C678DD;"> public</span><span> implementation;</span><span style="color: #7F848E;font-style: italic;"> // slot 0 -- must match Proxy</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">24</span><span style="color: #E5C07B;"> uint256</span><span style="color: #C678DD;"> public</span><span> value;</span><span style="color: #7F848E;font-style: italic;"> // slot 1 -- must match Proxy</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">25</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">26</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> setValue</span><span>(</span><span style="color: #E5C07B;">uint256</span><span style="font-style: italic;"> _value</span><span>)</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">27</span><span> value </span><span style="color: #56B6C2;">=</span><span> _value;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">28</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">29</span><span>}</span></span></code></pre> <p>Any call to <code>Proxy</code> that does not match a defined function falls through to the <code>fallback</code>, which forwards the call to <code>Implementation</code> using <code>delegatecall</code>. The proxy's storage is modified, not the implementation's.</p> <p>To upgrade, deploy a new implementation contract and update <code>implementation</code> in the proxy. Users never need to change the address they call.</p> <blockquote class="markdown-alert-note"> <p>Real-world proxy patterns like OpenZeppelin's UUPS and Transparent Proxy use more sophisticated storage slot management (EIP-1967) to avoid layout collisions between proxy admin variables and logic variables.</p> </blockquote> <h2 id="key-differences-side-by-side">Key Differences Side by Side</h2> <table><thead><tr><th>Property</th><th>call</th><th>delegatecall</th></tr></thead><tbody> <tr><td><code>msg.sender</code></td><td>Calling contract's address</td><td>Original transaction sender</td></tr> <tr><td><code>msg.value</code></td><td>Value sent with the call</td><td>Original transaction value</td></tr> <tr><td><code>this</code></td><td>Target contract</td><td>Calling contract</td></tr> <tr><td>Storage modified</td><td>Target contract's storage</td><td>Calling contract's storage</td></tr> <tr><td>Typical use</td><td>Sending Ether, generic calls</td><td>Proxy patterns, upgradeable contracts</td></tr> </tbody></table> <h2 id="security-the-difference-matters">Security: The Difference Matters</h2> <p>The distinction between <code>call</code> and <code>delegatecall</code> has direct security implications. Consider this:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="security-example.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Target</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #E5C07B;"> address</span><span style="color: #C678DD;"> public</span><span> owner;</span><span style="color: #7F848E;font-style: italic;"> // slot 0</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> changeOwner</span><span>(</span><span style="color: #E5C07B;">address</span><span style="font-style: italic;"> _newOwner</span><span>)</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span> owner </span><span style="color: #56B6C2;">=</span><span> _newOwner;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Victim</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #E5C07B;"> address</span><span style="color: #C678DD;"> public</span><span> owner;</span><span style="color: #7F848E;font-style: italic;"> // slot 0</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> doCall</span><span>(</span><span style="color: #E5C07B;">address</span><span style="font-style: italic;"> _target</span><span>)</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span style="color: #7F848E;font-style: italic;"> // call: changes Target&#39;s owner, Victim is unaffected</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span> (</span><span style="color: #E5C07B;">bool</span><span> s1, )</span><span style="color: #56B6C2;"> =</span><span> _target.</span><span style="color: #61AFEF;">call</span><span>(</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span style="color: #E5C07B;"> abi</span><span>.</span><span style="color: #61AFEF;">encodeWithSignature</span><span>(</span><span style="color: #98C379;">&quot;changeOwner(address)&quot;</span><span>,</span><span style="color: #E5C07B;"> address</span><span>(</span><span style="color: #E5C07B;">this</span><span>))</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span> );</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">17</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">18</span><span style="color: #7F848E;font-style: italic;"> // delegatecall: changes Victim&#39;s owner, Target is unaffected</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">19</span><span> (</span><span style="color: #E5C07B;">bool</span><span> s2, )</span><span style="color: #56B6C2;"> =</span><span> _target.</span><span style="color: #61AFEF;">delegatecall</span><span>(</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">20</span><span style="color: #E5C07B;"> abi</span><span>.</span><span style="color: #61AFEF;">encodeWithSignature</span><span>(</span><span style="color: #98C379;">&quot;changeOwner(address)&quot;</span><span>,</span><span style="color: #E5C07B;"> address</span><span>(</span><span style="color: #E5C07B;">this</span><span>))</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">21</span><span> );</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">22</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">23</span><span>}</span></span></code></pre> <p>The <code>call</code> version modifies <code>Target.owner</code>. The <code>delegatecall</code> version modifies <code>Victim.owner</code>. If an attacker controls the logic contract passed to a <code>delegatecall</code>, they can overwrite any storage slot in your contract, including ownership and access control variables.</p> <p>Never use <code>delegatecall</code> with an untrusted address.</p> <h2 id="error-handling">Error Handling</h2> <p>Neither <code>call</code> nor <code>delegatecall</code> reverts automatically on failure. Both return a <code>success</code> boolean. If you ignore it, your contract continues executing after a failed call, which leads to subtle and hard-to-debug bugs.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="error-handling.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> ErrorHandler</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> safeCall</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> target</span><span>)</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span> (</span><span style="color: #E5C07B;">bool</span><span> success,</span><span style="color: #E5C07B;"> bytes</span><span style="color: #C678DD;"> memory</span><span> returnData)</span><span style="color: #56B6C2;"> =</span><span> target.</span><span style="color: #61AFEF;">call</span><span>(</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #E5C07B;"> abi</span><span>.</span><span style="color: #61AFEF;">encodeWithSignature</span><span>(</span><span style="color: #98C379;">&quot;someFunction()&quot;</span><span>)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span> );</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #C678DD;"> if</span><span> (!success) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #C678DD;"> if</span><span> (returnData.length &gt;</span><span style="color: #D19A66;"> 0</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #7F848E;font-style: italic;"> // Bubble up the revert reason from the failed call</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #C678DD;"> assembly</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span style="color: #C678DD;"> revert</span><span>(</span><span style="color: #61AFEF;">add</span><span>(returnData,</span><span style="color: #D19A66;"> 32</span><span>),</span><span style="color: #61AFEF;"> mload</span><span>(returnData))</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span> }</span><span style="color: #C678DD;"> else</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span style="color: #C678DD;"> revert</span><span>(</span><span style="color: #98C379;">&quot;Call failed without reason&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">17</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">18</span><span>}</span></span></code></pre> <p>The assembly block re-throws the original revert reason from the failed call. Without it, you lose the reason and get a generic error instead.</p> <h2 id="gas-forwarding">Gas Forwarding</h2> <p>Before Solidity 0.6.2, you had to manually specify gas when using <code>call</code>. Now it forwards all available gas by default. You can still override this when needed.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #7F848E;font-style: italic;">// Forwards all available gas (default since 0.6.2)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span>target.</span><span style="color: #61AFEF;">call</span><span>(data);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #7F848E;font-style: italic;">// Forwards all gas with Ether</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span>target.call{value:</span><span style="color: #D19A66;"> 1 ether</span><span>}(data);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #7F848E;font-style: italic;">// Explicit gas limit</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span>target.call{gas:</span><span style="color: #D19A66;"> 10000</span><span>}(data);</span></span></code></pre> <p>Forwarding all gas is usually what you want. Setting an explicit gas limit can cause calls to fail if the target needs more gas than you allowed.</p> <h2 id="a-practical-pattern-multicall">A Practical Pattern: MultiCall</h2> <p>One common real-world use of <code>call</code> is batching multiple contract interactions into a single transaction:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="multicall.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> MultiCall</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> multiCall</span><span>(</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #E5C07B;"> address</span><span>[]</span><span style="color: #C678DD;"> calldata</span><span style="color: #E06C75;font-style: italic;"> targets</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #E5C07B;"> bytes</span><span>[]</span><span style="color: #C678DD;"> calldata</span><span style="color: #E06C75;font-style: italic;"> data</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span> )</span><span style="color: #C678DD;"> external returns</span><span> (</span><span style="color: #E5C07B;">bytes</span><span>[]</span><span style="color: #C678DD;"> memory</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #C678DD;"> require</span><span>(targets.length == data.length,</span><span style="color: #98C379;"> &quot;Length mismatch&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #E5C07B;"> bytes</span><span>[]</span><span style="color: #C678DD;"> memory</span><span> results </span><span style="color: #56B6C2;">=</span><span style="color: #C678DD;"> new</span><span style="color: #E5C07B;"> bytes</span><span>[](</span><span style="color: #E06C75;font-style: italic;">targets</span><span>.</span><span style="color: #E06C75;font-style: italic;">length</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #C678DD;"> for</span><span> (</span><span style="color: #E5C07B;">uint256</span><span> i </span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> 0</span><span>; i &lt; targets.length; i</span><span style="color: #56B6C2;">++</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span> (</span><span style="color: #E5C07B;">bool</span><span> success,</span><span style="color: #E5C07B;"> bytes</span><span style="color: #C678DD;"> memory</span><span> result)</span><span style="color: #56B6C2;"> =</span><span> targets[i].</span><span style="color: #61AFEF;">call</span><span>(data[i]);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span style="color: #C678DD;"> require</span><span>(success,</span><span style="color: #98C379;"> &quot;Call failed&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span> results[i]</span><span style="color: #56B6C2;"> =</span><span> result;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span style="color: #C678DD;"> return</span><span> results;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">17</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">18</span><span>}</span></span></code></pre> <p>This pattern is used in DeFi protocols to batch reads or writes, reducing the number of round trips from the client.</p> <h2 id="summary">Summary</h2> <p>Use <code>call</code> for standard contract interactions, sending Ether, and interacting with contracts you do not have an interface for. It runs code in the target's context and keeps your state isolated.</p> <p>Use <code>delegatecall</code> when you need to borrow logic from another contract while keeping state in your own contract. The proxy upgrade pattern is the primary use case. When you use it, storage layout between contracts must match exactly, and the logic contract must be trusted code you control.</p> <p>Both functions skip automatic revert on failure. Always check the returned <code>success</code> value.</p> 2025-11-05T00:00:00+00:00 2025-11-05T00:00:00+00:00 Akash Vaghela https://akash11.com/blog/fallback-functions-in-solidity/ <p>Solidity has two special functions that handle incoming transactions your contract did not explicitly plan for: <code>receive()</code> and <code>fallback()</code>. They look similar, but they serve different purposes. This post explains what each function does, how Solidity decides which one to call, and how to use them correctly.</p> <h2 id="how-solidity-routes-incoming-transactions">How Solidity Routes Incoming Transactions</h2> <p>When a transaction arrives at your contract, Solidity runs through a decision tree before executing any code.</p> <p>First, it checks whether <code>msg.data</code> is empty.</p> <p>If <code>msg.data</code> is empty, Solidity looks for a <code>receive()</code> function. If one exists, it runs. If not, Solidity falls back to <code>fallback()</code>.</p> <p>If <code>msg.data</code> is not empty, Solidity skips <code>receive()</code> entirely and goes straight to <code>fallback()</code>.</p> <p>Here is that logic as a diagram:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="plain"><span class="giallo-l"><span> incoming transaction</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span> msg.data is empty?</span></span> <span class="giallo-l"><span> / \</span></span> <span class="giallo-l"><span> yes no</span></span> <span class="giallo-l"><span> | |</span></span> <span class="giallo-l"><span> receive() exists? fallback()</span></span> <span class="giallo-l"><span> / \</span></span> <span class="giallo-l"><span> yes no</span></span> <span class="giallo-l"><span> | |</span></span> <span class="giallo-l"><span> receive() fallback()</span></span></code></pre> <p>The separation is intentional. Plain Ether transfers have no data. Function calls and other interactions do. This lets you handle each case with different logic.</p> <h2 id="the-two-functions">The Two Functions</h2> <h3 id="receive">receive()</h3> <p><code>receive()</code> handles plain Ether transfers. When someone sends Ether to your contract without calling any function, this is what runs.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> ReceiveExample</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #C678DD;"> event</span><span style="color: #E5C07B;"> Received</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> sender</span><span>, </span><span style="color: #E5C07B;">uint</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">4</span><span style="color: #61AFEF;"> receive</span><span>()</span><span style="color: #C678DD;"> external payable</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">5</span><span style="color: #C678DD;"> emit</span><span style="color: #61AFEF;"> Received</span><span>(</span><span style="color: #E5C07B;">msg.sender</span><span>,</span><span style="color: #E5C07B;"> msg</span><span>.value);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">6</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">7</span><span>}</span></span></code></pre> <p><code>receive()</code> must be <code>external</code> and <code>payable</code>. It takes no parameters and returns nothing.</p> <h3 id="fallback">fallback()</h3> <p><code>fallback()</code> is the catch-all. It runs when someone calls a function that does not exist on your contract, or when Ether arrives with data but no <code>receive()</code> function is defined.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> FallbackExample</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #C678DD;"> event</span><span style="color: #E5C07B;"> FallbackCalled</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> sender</span><span>, </span><span style="color: #E5C07B;">uint</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>, </span><span style="color: #E5C07B;">bytes</span><span style="color: #E06C75;font-style: italic;"> data</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">4</span><span style="color: #61AFEF;"> fallback</span><span>()</span><span style="color: #C678DD;"> external payable</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">5</span><span style="color: #C678DD;"> emit</span><span style="color: #61AFEF;"> FallbackCalled</span><span>(</span><span style="color: #E5C07B;">msg.sender</span><span>,</span><span style="color: #E5C07B;"> msg</span><span>.value,</span><span style="color: #E5C07B;"> msg</span><span>.data);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">6</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">7</span><span>}</span></span></code></pre> <p>Like <code>receive()</code>, <code>fallback()</code> must be <code>external</code>. The <code>payable</code> modifier is optional. Without it, your fallback function will reject any Ether sent with the call.</p> <h2 id="a-complete-example">A Complete Example</h2> <p>This contract implements both functions and logs which one was triggered:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="TestContract.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> TestContract</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;"> event</span><span style="color: #E5C07B;"> Log</span><span>(</span><span style="color: #E5C07B;">string</span><span style="color: #E06C75;font-style: italic;"> func</span><span>, </span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> sender</span><span>, </span><span style="color: #E5C07B;">uint</span><span style="color: #E06C75;font-style: italic;"> value</span><span>, </span><span style="color: #E5C07B;">bytes</span><span style="color: #E06C75;font-style: italic;"> data</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #61AFEF;"> fallback</span><span>()</span><span style="color: #C678DD;"> external payable</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #C678DD;"> emit</span><span style="color: #61AFEF;"> Log</span><span>(</span><span style="color: #98C379;">&quot;fallback&quot;</span><span>,</span><span style="color: #E5C07B;"> msg.sender</span><span>,</span><span style="color: #E5C07B;"> msg</span><span>.value,</span><span style="color: #E5C07B;"> msg</span><span>.data);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #61AFEF;"> receive</span><span>()</span><span style="color: #C678DD;"> external payable</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #C678DD;"> emit</span><span style="color: #61AFEF;"> Log</span><span>(</span><span style="color: #98C379;">&quot;receive&quot;</span><span>,</span><span style="color: #E5C07B;"> msg.sender</span><span>,</span><span style="color: #E5C07B;"> msg</span><span>.value,</span><span style="color: #98C379;"> &quot;&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span>}</span></span></code></pre> <p>And here is a contract to test it:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="Sender.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Sender</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> sendToReceive</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> payable target</span><span>)</span><span style="color: #C678DD;"> public payable</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #7F848E;font-style: italic;"> // Empty data, so receive() runs</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span> target.call{value:</span><span style="color: #E5C07B;"> msg</span><span>.value}(</span><span style="color: #98C379;">&quot;&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> sendToFallback</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> payable target</span><span>)</span><span style="color: #C678DD;"> public payable</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #7F848E;font-style: italic;"> // Non-empty data, so fallback() runs</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span> target.call{value:</span><span style="color: #E5C07B;"> msg</span><span>.value}(</span><span style="color: #E5C07B;">abi</span><span>.</span><span style="color: #61AFEF;">encodeWithSignature</span><span>(</span><span style="color: #98C379;">&quot;nonExistentFunc()&quot;</span><span>));</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span>}</span></span></code></pre> <p>When <code>sendToReceive</code> runs, <code>msg.data</code> is empty, so <code>receive()</code> executes. When <code>sendToFallback</code> runs, <code>msg.data</code> contains the encoded function signature, so <code>fallback()</code> executes.</p> <h2 id="what-happens-with-only-one-function">What Happens With Only One Function</h2> <h3 id="only-fallback-no-receive">Only fallback(), no receive()</h3> <p>If you define <code>fallback()</code> but not <code>receive()</code>, all incoming transactions route through <code>fallback()</code>. Plain Ether transfers and calls with data both end up there.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> OnlyFallback</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #C678DD;"> event</span><span style="color: #E5C07B;"> Log</span><span>(</span><span style="color: #E5C07B;">string</span><span style="color: #E06C75;font-style: italic;"> message</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">4</span><span style="color: #61AFEF;"> fallback</span><span>()</span><span style="color: #C678DD;"> external payable</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">5</span><span style="color: #C678DD;"> emit</span><span style="color: #61AFEF;"> Log</span><span>(</span><span style="color: #98C379;">&quot;all transactions come here&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">6</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">7</span><span>}</span></span></code></pre> <p>This works, but you lose the ability to distinguish between plain transfers and unexpected function calls.</p> <h3 id="only-receive-no-fallback">Only receive(), no fallback()</h3> <p>If you define <code>receive()</code> but not <code>fallback()</code>, calls to non-existent functions will revert. There is nothing to catch them.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> OnlyReceive</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #C678DD;"> event</span><span style="color: #E5C07B;"> Log</span><span>(</span><span style="color: #E5C07B;">string</span><span style="color: #E06C75;font-style: italic;"> message</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">4</span><span style="color: #61AFEF;"> receive</span><span>()</span><span style="color: #C678DD;"> external payable</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">5</span><span style="color: #C678DD;"> emit</span><span style="color: #61AFEF;"> Log</span><span>(</span><span style="color: #98C379;">&quot;plain ether accepted&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">6</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">7</span><span>}</span></span></code></pre> <p>Plain Ether transfers work fine. Any call with data causes a revert.</p> <h2 id="a-real-wallet-example">A Real Wallet Example</h2> <p>Here is a pattern you will see in practice. The contract accepts plain Ether but explicitly rejects calls to functions that do not exist:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="Wallet.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Wallet</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;"> event</span><span style="color: #E5C07B;"> Deposit</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> from</span><span>, </span><span style="color: #E5C07B;">uint</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #C678DD;"> event</span><span style="color: #E5C07B;"> FallbackTriggered</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> from</span><span>, </span><span style="color: #E5C07B;">bytes</span><span style="color: #E06C75;font-style: italic;"> data</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #61AFEF;"> receive</span><span>()</span><span style="color: #C678DD;"> external payable</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #C678DD;"> emit</span><span style="color: #61AFEF;"> Deposit</span><span>(</span><span style="color: #E5C07B;">msg.sender</span><span>,</span><span style="color: #E5C07B;"> msg</span><span>.value);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #61AFEF;"> fallback</span><span>()</span><span style="color: #C678DD;"> external payable</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #C678DD;"> emit</span><span style="color: #61AFEF;"> FallbackTriggered</span><span>(</span><span style="color: #E5C07B;">msg.sender</span><span>,</span><span style="color: #E5C07B;"> msg</span><span>.data);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span style="color: #C678DD;"> revert</span><span>(</span><span style="color: #98C379;">&quot;Function does not exist&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span>}</span></span></code></pre> <p>Using <code>revert</code> in <code>fallback()</code> is a common defensive pattern. If someone accidentally sends a transaction with the wrong function signature, the call fails cleanly instead of silently doing nothing.</p> <h2 id="testing-which-function-runs">Testing Which Function Runs</h2> <p>This contract lets you verify the routing yourself:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="FlowTest.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> FlowTest</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #E5C07B;"> uint</span><span style="color: #C678DD;"> public</span><span> receiveCount;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #E5C07B;"> uint</span><span style="color: #C678DD;"> public</span><span> fallbackCount;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #61AFEF;"> receive</span><span>()</span><span style="color: #C678DD;"> external payable</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span> receiveCount</span><span style="color: #56B6C2;">++</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #61AFEF;"> fallback</span><span>()</span><span style="color: #C678DD;"> external payable</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span> fallbackCount</span><span style="color: #56B6C2;">++</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> getBalance</span><span>()</span><span style="color: #C678DD;"> public view returns</span><span> (</span><span style="color: #E5C07B;">uint</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span style="color: #C678DD;"> return</span><span style="color: #E5C07B;"> address</span><span>(</span><span style="color: #E5C07B;">this</span><span>).balance;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">17</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">18</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Tester</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">19</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> testReceive</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> payable target</span><span>)</span><span style="color: #C678DD;"> public payable</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">20</span><span> (</span><span style="color: #E5C07B;">bool</span><span> success,)</span><span style="color: #56B6C2;"> =</span><span> target.call{value:</span><span style="color: #E5C07B;"> msg</span><span>.value}(</span><span style="color: #98C379;">&quot;&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">21</span><span style="color: #C678DD;"> require</span><span>(success);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">22</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">23</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">24</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> testFallback</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> payable target</span><span>)</span><span style="color: #C678DD;"> public payable</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">25</span><span> (</span><span style="color: #E5C07B;">bool</span><span> success,)</span><span style="color: #56B6C2;"> =</span><span> target.call{value:</span><span style="color: #E5C07B;"> msg</span><span>.value}(</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">26</span><span style="color: #E5C07B;"> abi</span><span>.</span><span style="color: #61AFEF;">encodeWithSignature</span><span>(</span><span style="color: #98C379;">&quot;random()&quot;</span><span>)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">27</span><span> );</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">28</span><span style="color: #C678DD;"> require</span><span>(success);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">29</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">30</span><span>}</span></span></code></pre> <p>Deploy <code>FlowTest</code>, then call <code>testReceive</code> and <code>testFallback</code> from <code>Tester</code>. Check <code>receiveCount</code> and <code>fallbackCount</code> to see exactly which function ran.</p> <h2 id="key-rules">Key Rules</h2> <p>Both <code>receive()</code> and <code>fallback()</code> must be <code>external</code>. Using <code>public</code> will not compile:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #7F848E;font-style: italic;">// Correct</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #61AFEF;">receive</span><span>()</span><span style="color: #C678DD;"> external payable</span><span> { }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span><span style="color: #61AFEF;">fallback</span><span>()</span><span style="color: #C678DD;"> external payable</span><span> { }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">4</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">5</span><span style="color: #7F848E;font-style: italic;">// Will not compile</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">6</span><span style="color: #61AFEF;">receive</span><span>()</span><span style="color: #C678DD;"> public payable</span><span> { }</span></span></code></pre> <p>To accept Ether, the function must be <code>payable</code>. Without it, any Ether sent with the transaction causes a revert:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #7F848E;font-style: italic;">// Accepts Ether</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #61AFEF;">receive</span><span>()</span><span style="color: #C678DD;"> external payable</span><span> { }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">4</span><span style="color: #7F848E;font-style: italic;">// Rejects Ether</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">5</span><span style="color: #61AFEF;">receive</span><span>()</span><span style="color: #C678DD;"> external</span><span> { }</span></span></code></pre> <p>Neither function takes parameters or returns values. Attempting this will not compile:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #7F848E;font-style: italic;">// Will not compile</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #61AFEF;">fallback</span><span>(</span><span style="color: #E5C07B;">uint</span><span> x)</span><span style="color: #C678DD;"> external payable</span><span> { }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span><span style="color: #61AFEF;">fallback</span><span>()</span><span style="color: #C678DD;"> external payable returns</span><span> (</span><span style="color: #E5C07B;">uint</span><span>) { }</span></span></code></pre> <blockquote class="markdown-alert-warning"> <p>If neither <code>receive()</code> nor <code>fallback()</code> is defined, your contract cannot accept Ether at all. Any transfer will revert. This is a common source of bugs when integrating with contracts that send Ether back to callers.</p> </blockquote> <h2 id="summary">Summary</h2> <p><code>receive()</code> handles plain Ether transfers with empty <code>msg.data</code>. <code>fallback()</code> handles everything else: unknown function calls and Ether transfers with data when no <code>receive()</code> exists. Having both gives you clean separation between the two cases. Having only one or the other has specific tradeoffs worth understanding before you deploy.</p> 2025-11-05T00:00:00+00:00 2025-11-05T00:00:00+00:00 Akash Vaghela https://akash11.com/blog/sending-ether-in-solidity-with-transfer-send-call/ <p>Solidity gives you three ways to send Ether from a contract: <code>transfer</code>, <code>send</code>, and <code>call</code>. They look similar on the surface, but they behave very differently when it comes to gas, error handling, and security. Choosing the wrong one can break your contract or open it to attacks.</p> <p>This post covers how each method works, where they differ, and which one to use today.</p> <h2 id="the-three-methods">The Three Methods</h2> <h3 id="transfer">transfer</h3> <p><code>transfer</code> forwards a fixed <strong>2300 gas</strong> to the recipient and automatically reverts the entire transaction if the transfer fails. No return value. No manual error checking required.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> sendViaTransfer</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> payable</span><span style="font-style: italic;"> _to</span><span>)</span><span style="color: #C678DD;"> public payable</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span> _to.</span><span style="color: #61AFEF;">transfer</span><span>(</span><span style="color: #E5C07B;">msg</span><span>.value);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span><span>}</span></span></code></pre> <p>The 2300 gas stipend is intentionally small. It is enough for the recipient to emit an event, but not enough to make external calls or run complex logic. This was designed as a security feature to block reentrancy attacks.</p> <blockquote class="markdown-alert-warning"> <p>After the Istanbul hard fork (EIP-1884, 2019), the gas cost of <code>SLOAD</code> increased from 200 to 800. This means some recipient contracts that used to work fine with 2300 gas now run out of gas and cause <code>transfer</code> to fail. Contracts you did not write might break without any code change on your end.</p> </blockquote> <h3 id="send">send</h3> <p><code>send</code> also forwards 2300 gas, but instead of reverting on failure, it returns a <code>bool</code>. You are responsible for checking it.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> sendViaSend</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> payable</span><span style="font-style: italic;"> _to</span><span>)</span><span style="color: #C678DD;"> public payable</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #E5C07B;"> bool</span><span> sent </span><span style="color: #56B6C2;">=</span><span> _to.</span><span style="color: #61AFEF;">send</span><span>(</span><span style="color: #E5C07B;">msg</span><span>.value);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span><span style="color: #C678DD;"> require</span><span>(sent,</span><span style="color: #98C379;"> &quot;Failed to send Ether&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">4</span><span>}</span></span></code></pre> <p>If you forget to check the return value, your contract continues executing as if the transfer succeeded, even when it did not. This is a real bug pattern. The Solidity compiler will warn you, but it will not stop you.</p> <p><code>send</code> has the same gas-related problems as <code>transfer</code>. There is almost no reason to use it over <code>transfer</code> (if you want automatic revert) or <code>call</code> (if you want flexibility).</p> <h3 id="call">call</h3> <p><code>call</code> is a low-level function. It forwards all remaining gas by default and returns two values: a success boolean and any returned bytes.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> sendViaCall</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> payable</span><span style="font-style: italic;"> _to</span><span>)</span><span style="color: #C678DD;"> public payable</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span> (</span><span style="color: #E5C07B;">bool</span><span> sent,</span><span style="color: #E5C07B;"> bytes</span><span style="color: #C678DD;"> memory</span><span> data)</span><span style="color: #56B6C2;"> =</span><span> _to.call{value:</span><span style="color: #E5C07B;"> msg</span><span>.value}(</span><span style="color: #98C379;">&quot;&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span><span style="color: #C678DD;"> require</span><span>(sent,</span><span style="color: #98C379;"> &quot;Failed to send Ether&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">4</span><span>}</span></span></code></pre> <p>The <code>{value: msg.value}</code> syntax sets how much Ether to send. The empty string <code>""</code> means you are not calling a specific function on the recipient, just sending Ether.</p> <p>You can also specify a custom gas limit:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span>(</span><span style="color: #E5C07B;">bool</span><span> sent, )</span><span style="color: #56B6C2;"> =</span><span> _to.call{value:</span><span style="color: #E5C07B;"> msg</span><span>.value, gas:</span><span style="color: #D19A66;"> 10000</span><span>}(</span><span style="color: #98C379;">&quot;&quot;</span><span>);</span></span></code></pre> <p>Because <code>call</code> forwards all gas, the recipient can run complex logic. This makes it flexible, but it also means reentrancy attacks become possible if you are not careful.</p> <hr /> <h2 id="comparison-at-a-glance">Comparison at a Glance</h2> <table><thead><tr><th>Method</th><th>Gas forwarded</th><th>On failure</th><th>Manual check needed</th></tr></thead><tbody> <tr><td><code>transfer</code></td><td>2300 (fixed)</td><td>Reverts automatically</td><td>No</td></tr> <tr><td><code>send</code></td><td>2300 (fixed)</td><td>Returns <code>false</code></td><td>Yes</td></tr> <tr><td><code>call</code></td><td>All remaining (configurable)</td><td>Returns <code>false</code></td><td>Yes</td></tr> </tbody></table> <hr /> <h2 id="which-method-to-use">Which Method to Use</h2> <p>Use <code>call</code>.</p> <p>After EIP-1884, the 2300 gas limit is no longer a reliable safety net. <code>transfer</code> and <code>send</code> can silently break when interacting with contracts that have non-trivial fallback logic. <code>call</code> avoids this by not capping gas, and it gives you full control over error handling.</p> <p>The tradeoff is that <code>call</code> requires you to handle reentrancy yourself. The standard approach is the <strong>checks-effects-interactions</strong> pattern: update all state before making any external call.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="SafeSender.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> SafeSender</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;"> mapping</span><span>(</span><span style="color: #E5C07B;">address</span><span> =&gt;</span><span style="color: #E5C07B;"> uint</span><span>)</span><span style="color: #C678DD;"> public</span><span> balances;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> withdraw</span><span>()</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #E5C07B;"> uint</span><span> amount </span><span style="color: #56B6C2;">=</span><span> balances[</span><span style="color: #E5C07B;">msg.sender</span><span>];</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #7F848E;font-style: italic;"> // Check</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #C678DD;"> require</span><span>(amount &gt;</span><span style="color: #D19A66;"> 0</span><span>,</span><span style="color: #98C379;"> &quot;Nothing to withdraw&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #7F848E;font-style: italic;"> // Effect: update state before external call</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span> balances[</span><span style="color: #E5C07B;">msg.sender</span><span>]</span><span style="color: #56B6C2;"> =</span><span style="color: #D19A66;"> 0</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span style="color: #7F848E;font-style: italic;"> // Interaction: send Ether last</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span> (</span><span style="color: #E5C07B;">bool</span><span> success, )</span><span style="color: #56B6C2;"> =</span><span style="color: #E5C07B;"> msg.sender</span><span>.call{value: amount}(</span><span style="color: #98C379;">&quot;&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span style="color: #C678DD;"> require</span><span>(success,</span><span style="color: #98C379;"> &quot;Transfer failed&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">17</span><span>}</span></span></code></pre> <p>The balance is set to zero before calling <code>call</code>. Even if the recipient re-enters <code>withdraw</code>, their balance is already zero, so they get nothing on the second call.</p> <p>If your withdrawal logic is more complex, consider a reentrancy guard instead of relying solely on ordering:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="ReentrancyGuard.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> SafeSenderWithGuard</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;"> mapping</span><span>(</span><span style="color: #E5C07B;">address</span><span> =&gt;</span><span style="color: #E5C07B;"> uint</span><span>)</span><span style="color: #C678DD;"> public</span><span> balances;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #E5C07B;"> bool</span><span style="color: #C678DD;"> private</span><span> locked;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #C678DD;"> modifier</span><span style="color: #61AFEF;"> noReentrant</span><span>() {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #C678DD;"> require</span><span>(!locked,</span><span style="color: #98C379;"> &quot;No reentrancy&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span> locked </span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> true</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #D19A66;"> _</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span> locked </span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> false</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> withdraw</span><span>()</span><span style="color: #C678DD;"> public</span><span style="color: #61AFEF;"> noReentrant</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span style="color: #E5C07B;"> uint</span><span> amount </span><span style="color: #56B6C2;">=</span><span> balances[</span><span style="color: #E5C07B;">msg.sender</span><span>];</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span style="color: #C678DD;"> require</span><span>(amount &gt;</span><span style="color: #D19A66;"> 0</span><span>,</span><span style="color: #98C379;"> &quot;Nothing to withdraw&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span> balances[</span><span style="color: #E5C07B;">msg.sender</span><span>]</span><span style="color: #56B6C2;"> =</span><span style="color: #D19A66;"> 0</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">17</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">18</span><span> (</span><span style="color: #E5C07B;">bool</span><span> success, )</span><span style="color: #56B6C2;"> =</span><span style="color: #E5C07B;"> msg.sender</span><span>.call{value: amount}(</span><span style="color: #98C379;">&quot;&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">19</span><span style="color: #C678DD;"> require</span><span>(success,</span><span style="color: #98C379;"> &quot;Transfer failed&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">20</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">21</span><span>}</span></span></code></pre> <hr /> <h2 id="receiving-ether-in-a-contract">Receiving Ether in a Contract</h2> <p>For a contract to receive Ether sent via <code>call</code>, it needs at least one of these functions:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> EtherReceiver</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;"> event</span><span style="color: #E5C07B;"> Received</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> sender</span><span>, </span><span style="color: #E5C07B;">uint</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #7F848E;font-style: italic;"> // Called when msg.data is empty (plain Ether transfer)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #61AFEF;"> receive</span><span>()</span><span style="color: #C678DD;"> external payable</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #C678DD;"> emit</span><span style="color: #61AFEF;"> Received</span><span>(</span><span style="color: #E5C07B;">msg.sender</span><span>,</span><span style="color: #E5C07B;"> msg</span><span>.value);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #7F848E;font-style: italic;"> // Called when no other function matches</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #61AFEF;"> fallback</span><span>()</span><span style="color: #C678DD;"> external payable</span><span> {}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span>}</span></span></code></pre> <p><code>receive</code> handles plain Ether transfers with no calldata. <code>fallback</code> catches everything else. If neither exists, the contract will reject incoming Ether and cause your <code>call</code> to fail.</p> <hr /> <h2 id="full-working-example">Full Working Example</h2> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="EtherSender.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #7F848E;font-style: italic;">// SPDX-License-Identifier: MIT</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;">pragma</span><span style="color: #E06C75;"> solidity</span><span style="color: #D19A66;"> ^0.8.0</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> EtherSender</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> sendViaTransfer</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> payable</span><span style="font-style: italic;"> _to</span><span>)</span><span style="color: #C678DD;"> public payable</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span> _to.</span><span style="color: #61AFEF;">transfer</span><span>(</span><span style="color: #E5C07B;">msg</span><span>.value);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> sendViaSend</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> payable</span><span style="font-style: italic;"> _to</span><span>)</span><span style="color: #C678DD;"> public payable</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #E5C07B;"> bool</span><span> sent </span><span style="color: #56B6C2;">=</span><span> _to.</span><span style="color: #61AFEF;">send</span><span>(</span><span style="color: #E5C07B;">msg</span><span>.value);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span style="color: #C678DD;"> require</span><span>(sent,</span><span style="color: #98C379;"> &quot;Send failed&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> sendViaCall</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> payable</span><span style="font-style: italic;"> _to</span><span>)</span><span style="color: #C678DD;"> public payable</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span> (</span><span style="color: #E5C07B;">bool</span><span> sent, )</span><span style="color: #56B6C2;"> =</span><span> _to.call{value:</span><span style="color: #E5C07B;"> msg</span><span>.value}(</span><span style="color: #98C379;">&quot;&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span style="color: #C678DD;"> require</span><span>(sent,</span><span style="color: #98C379;"> &quot;Call failed&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">17</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">18</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">19</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">20</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> EtherReceiver</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">21</span><span style="color: #C678DD;"> event</span><span style="color: #E5C07B;"> Received</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> sender</span><span>, </span><span style="color: #E5C07B;">uint</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">22</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">23</span><span style="color: #61AFEF;"> receive</span><span>()</span><span style="color: #C678DD;"> external payable</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">24</span><span style="color: #C678DD;"> emit</span><span style="color: #61AFEF;"> Received</span><span>(</span><span style="color: #E5C07B;">msg.sender</span><span>,</span><span style="color: #E5C07B;"> msg</span><span>.value);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">25</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">26</span><span>}</span></span></code></pre> <p>When you call <code>sendViaCall</code> with 1 Ether and pass an <code>EtherReceiver</code> address, the Ether is forwarded and the <code>Received</code> event is emitted. The other two methods will also work with this receiver, but they carry the gas-limit risk described above.</p> <hr /> <h2 id="conclusion">Conclusion</h2> <p>Use <code>call</code> for sending Ether in any contract you write today. Always check the boolean return value. Always update contract state before the external call.</p> <p><code>transfer</code> and <code>send</code> exist in older contracts and tutorials, so you will see them. But the gas assumptions they rely on are no longer safe after Istanbul. <code>call</code> with the checks-effects-interactions pattern (or a reentrancy guard) is the right approach.</p> 2025-11-04T00:00:00+00:00 2025-11-04T00:00:00+00:00 Akash Vaghela https://akash11.com/blog/inheritance-in-solidity/ <p>Solidity lets contracts inherit from other contracts. The child contract gets all the public and internal functions and state variables of the parent. This lets you split logic across multiple focused contracts and reuse it across your codebase without copying code.</p> <p>This post covers the four core mechanisms: <code>is</code>, <code>virtual</code>, <code>override</code>, and <code>super</code>. It also covers multiple inheritance, how Solidity resolves conflicts between parents, and a few mistakes worth knowing about before they bite you.</p> <h2 id="the-is-keyword">The <code>is</code> Keyword</h2> <p><code>is</code> establishes the inheritance relationship. Write <code>contract Child is Parent</code> and the child contract inherits everything that is not private.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="direct-inheritance.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #7F848E;font-style: italic;">// SPDX-License-Identifier: MIT</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;">pragma</span><span style="color: #E06C75;"> solidity</span><span style="color: #D19A66;"> ^0.8.0</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Animal</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #E5C07B;"> string</span><span style="color: #C678DD;"> public</span><span> name;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> makeSound</span><span>()</span><span style="color: #C678DD;"> public pure virtual returns</span><span> (</span><span style="color: #E5C07B;">string</span><span style="color: #C678DD;"> memory</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #C678DD;"> return</span><span style="color: #98C379;"> &quot;Some sound&quot;</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Dog</span><span style="color: #C678DD;"> is</span><span style="color: #E5C07B;"> Animal</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> makeSound</span><span>()</span><span style="color: #C678DD;"> public pure override returns</span><span> (</span><span style="color: #E5C07B;">string</span><span style="color: #C678DD;"> memory</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span style="color: #C678DD;"> return</span><span style="color: #98C379;"> &quot;Woof!&quot;</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span>}</span></span></code></pre> <p><code>Dog</code> gets <code>name</code> from <code>Animal</code> for free. It replaces <code>makeSound</code> with its own version.</p> <h2 id="virtual-and-override"><code>virtual</code> and <code>override</code></h2> <p>These two keywords always work together.</p> <p><code>virtual</code> marks a function in the parent as replaceable. Without it, child contracts cannot override the function. Solidity will throw a compiler error if they try.</p> <p><code>override</code> marks a function in the child as a replacement for a parent's <code>virtual</code> function. Without it, the compiler will also error. This is intentional. Both sides must opt in.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="virtual-override.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Base</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #7F848E;font-style: italic;"> // Child contracts can replace this</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> calculate</span><span>()</span><span style="color: #C678DD;"> public pure virtual returns</span><span> (</span><span style="color: #E5C07B;">uint</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;"> return</span><span style="color: #D19A66;"> 5</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #7F848E;font-style: italic;"> // Child contracts cannot replace this</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> fixedFunction</span><span>()</span><span style="color: #C678DD;"> public pure returns</span><span> (</span><span style="color: #E5C07B;">uint</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #C678DD;"> return</span><span style="color: #D19A66;"> 10</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Derived</span><span style="color: #C678DD;"> is</span><span style="color: #E5C07B;"> Base</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> calculate</span><span>()</span><span style="color: #C678DD;"> public pure override returns</span><span> (</span><span style="color: #E5C07B;">uint</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span style="color: #C678DD;"> return</span><span style="color: #D19A66;"> 99</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">17</span><span>}</span></span></code></pre> <p>If you write a function in the child that matches a parent function's name but forget <code>override</code>, Solidity errors. This prevents accidental shadowing.</p> <h2 id="the-super-keyword">The <code>super</code> Keyword</h2> <p><code>super</code> calls the function from the parent contract. Use it when you want to extend the parent's behavior rather than fully replace it.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="super.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Counter</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #E5C07B;"> uint</span><span style="color: #C678DD;"> public</span><span> count;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> increment</span><span>()</span><span style="color: #C678DD;"> public virtual</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span> count </span><span style="color: #56B6C2;">+=</span><span style="color: #D19A66;"> 1</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> DoubleCounter</span><span style="color: #C678DD;"> is</span><span style="color: #E5C07B;"> Counter</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> increment</span><span>()</span><span style="color: #C678DD;"> public override</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span style="color: #E5C07B;font-style: italic;"> super</span><span>.</span><span style="color: #61AFEF;">increment</span><span>();</span><span style="color: #7F848E;font-style: italic;"> // runs parent logic</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span style="color: #E5C07B;font-style: italic;"> super</span><span>.</span><span style="color: #61AFEF;">increment</span><span>();</span><span style="color: #7F848E;font-style: italic;"> // runs it again</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span>}</span></span></code></pre> <p>Without <code>super</code>, calling <code>increment()</code> in the child would only run the child's logic. The parent's logic would be skipped entirely.</p> <h2 id="multiple-inheritance">Multiple Inheritance</h2> <p>A contract can inherit from more than one parent.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="multiple-parents.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> A</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> foo</span><span>()</span><span style="color: #C678DD;"> public pure virtual returns</span><span> (</span><span style="color: #E5C07B;">string</span><span style="color: #C678DD;"> memory</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #C678DD;"> return</span><span style="color: #98C379;"> &quot;A&quot;</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> B</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> bar</span><span>()</span><span style="color: #C678DD;"> public pure virtual returns</span><span> (</span><span style="color: #E5C07B;">string</span><span style="color: #C678DD;"> memory</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #C678DD;"> return</span><span style="color: #98C379;"> &quot;B&quot;</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> C</span><span style="color: #C678DD;"> is</span><span style="color: #E5C07B;"> A</span><span>, </span><span style="color: #E5C07B;">B</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> getValues</span><span>()</span><span style="color: #C678DD;"> public pure returns</span><span> (</span><span style="color: #E5C07B;">string</span><span style="color: #C678DD;"> memory</span><span>,</span><span style="color: #E5C07B;"> string</span><span style="color: #C678DD;"> memory</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span style="color: #C678DD;"> return</span><span> (</span><span style="color: #61AFEF;">foo</span><span>(),</span><span style="color: #61AFEF;"> bar</span><span>());</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">17</span><span>}</span></span></code></pre> <p><code>C</code> has access to both <code>foo</code> from <code>A</code> and <code>bar</code> from <code>B</code>.</p> <p>The situation gets more complex when two parents define the same function name.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="conflict.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> X</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> getValue</span><span>()</span><span style="color: #C678DD;"> public pure virtual returns</span><span> (</span><span style="color: #E5C07B;">uint</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #C678DD;"> return</span><span style="color: #D19A66;"> 1</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Y</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> getValue</span><span>()</span><span style="color: #C678DD;"> public pure virtual returns</span><span> (</span><span style="color: #E5C07B;">uint</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #C678DD;"> return</span><span style="color: #D19A66;"> 2</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Z</span><span style="color: #C678DD;"> is</span><span style="color: #E5C07B;"> X</span><span>, </span><span style="color: #E5C07B;">Y</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span style="color: #7F848E;font-style: italic;"> // Must override explicitly, listing both parents</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> getValue</span><span>()</span><span style="color: #C678DD;"> public pure override</span><span>(</span><span style="color: #61AFEF;">X</span><span>,</span><span style="color: #61AFEF;"> Y</span><span>)</span><span style="color: #C678DD;"> returns</span><span> (</span><span style="color: #E5C07B;">uint</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span style="color: #C678DD;"> return</span><span style="color: #D19A66;"> 3</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">17</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">18</span><span>}</span></span></code></pre> <p>When a function exists in multiple parents, you must list all of them inside <code>override(...)</code>. If you do not override at all, the compiler refuses to compile because it cannot decide which parent's version to use.</p> <h2 id="inheritance-order-and-c3-linearization">Inheritance Order and C3 Linearization</h2> <p>Solidity resolves multiple inheritance using C3 linearization. The practical rule: list parent contracts from most general to most specific, left to right. Solidity processes them right to left internally.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="linearization.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Base1</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> greet</span><span>()</span><span style="color: #C678DD;"> public pure virtual returns</span><span> (</span><span style="color: #E5C07B;">string</span><span style="color: #C678DD;"> memory</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #C678DD;"> return</span><span style="color: #98C379;"> &quot;Hello from Base1&quot;</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Base2</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> greet</span><span>()</span><span style="color: #C678DD;"> public pure virtual returns</span><span> (</span><span style="color: #E5C07B;">string</span><span style="color: #C678DD;"> memory</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #C678DD;"> return</span><span style="color: #98C379;"> &quot;Hello from Base2&quot;</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Derived</span><span style="color: #C678DD;"> is</span><span style="color: #E5C07B;"> Base1</span><span>, </span><span style="color: #E5C07B;">Base2</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> greet</span><span>()</span><span style="color: #C678DD;"> public pure override</span><span>(</span><span style="color: #61AFEF;">Base1</span><span>,</span><span style="color: #61AFEF;"> Base2</span><span>)</span><span style="color: #C678DD;"> returns</span><span> (</span><span style="color: #E5C07B;">string</span><span style="color: #C678DD;"> memory</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span style="color: #C678DD;"> return</span><span style="color: #98C379;"> &quot;Hello from Derived&quot;</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">17</span><span>}</span></span></code></pre> <p>This matters most when using <code>super</code> in a chain of contracts. Solidity will walk the chain in linearized order.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="super-chain.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> A</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;"> event</span><span style="color: #E5C07B;"> Log</span><span>(</span><span style="color: #E5C07B;">string</span><span style="color: #E06C75;font-style: italic;"> message</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> process</span><span>()</span><span style="color: #C678DD;"> public virtual</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #C678DD;"> emit</span><span style="color: #61AFEF;"> Log</span><span>(</span><span style="color: #98C379;">&quot;A processed&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> B</span><span style="color: #C678DD;"> is</span><span style="color: #E5C07B;"> A</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> process</span><span>()</span><span style="color: #C678DD;"> public virtual override</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span style="color: #C678DD;"> emit</span><span style="color: #61AFEF;"> Log</span><span>(</span><span style="color: #98C379;">&quot;B processed&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span style="color: #E5C07B;font-style: italic;"> super</span><span>.</span><span style="color: #61AFEF;">process</span><span>();</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> C</span><span style="color: #C678DD;"> is</span><span style="color: #E5C07B;"> A</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">17</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> process</span><span>()</span><span style="color: #C678DD;"> public virtual override</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">18</span><span style="color: #C678DD;"> emit</span><span style="color: #61AFEF;"> Log</span><span>(</span><span style="color: #98C379;">&quot;C processed&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">19</span><span style="color: #E5C07B;font-style: italic;"> super</span><span>.</span><span style="color: #61AFEF;">process</span><span>();</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">20</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">21</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">22</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">23</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> D</span><span style="color: #C678DD;"> is</span><span style="color: #E5C07B;"> B</span><span>, </span><span style="color: #E5C07B;">C</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">24</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> process</span><span>()</span><span style="color: #C678DD;"> public override</span><span>(</span><span style="color: #61AFEF;">B</span><span>,</span><span style="color: #61AFEF;"> C</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">25</span><span style="color: #E5C07B;font-style: italic;"> super</span><span>.</span><span style="color: #61AFEF;">process</span><span>();</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">26</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">27</span><span>}</span></span></code></pre> <p>When <code>D</code> calls <code>super.process()</code>, the linearized order is <code>D, C, B, A</code>. So <code>C.process()</code> runs first, then <code>B.process()</code>, then <code>A.process()</code>. Each call to <code>super</code> passes control to the next in that chain.</p> <blockquote class="markdown-alert-note"> <p>The linearization order is deterministic and computed at compile time. Solidity will reject inheritance hierarchies that cannot be linearized cleanly.</p> </blockquote> <h2 id="a-practical-example">A Practical Example</h2> <p>Here is a pattern you will see often in real contracts: a <code>Token</code> that is both ownable and pausable.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="token.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #7F848E;font-style: italic;">// SPDX-License-Identifier: MIT</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;">pragma</span><span style="color: #E06C75;"> solidity</span><span style="color: #D19A66;"> ^0.8.0</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Ownable</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #E5C07B;"> address</span><span style="color: #C678DD;"> public</span><span> owner;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #C678DD;"> constructor</span><span>() {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span> owner </span><span style="color: #56B6C2;">=</span><span style="color: #E5C07B;"> msg.sender</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span style="color: #C678DD;"> modifier</span><span style="color: #61AFEF;"> onlyOwner</span><span>() {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span style="color: #C678DD;"> require</span><span>(</span><span style="color: #E5C07B;">msg.sender</span><span> == owner,</span><span style="color: #98C379;"> &quot;Not owner&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span style="color: #D19A66;"> _</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> transferOwnership</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> newOwner</span><span>)</span><span style="color: #C678DD;"> public virtual</span><span style="color: #61AFEF;"> onlyOwner</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">17</span><span> owner </span><span style="color: #56B6C2;">=</span><span> newOwner;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">18</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">19</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">20</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">21</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Pausable</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">22</span><span style="color: #E5C07B;"> bool</span><span style="color: #C678DD;"> public</span><span> paused;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">23</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">24</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> pause</span><span>()</span><span style="color: #C678DD;"> public virtual</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">25</span><span> paused </span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> true</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">26</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">27</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">28</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> unpause</span><span>()</span><span style="color: #C678DD;"> public virtual</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">29</span><span> paused </span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> false</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">30</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">31</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">32</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">33</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Token</span><span style="color: #C678DD;"> is</span><span style="color: #E5C07B;"> Ownable</span><span>, </span><span style="color: #E5C07B;">Pausable</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">34</span><span style="color: #C678DD;"> mapping</span><span>(</span><span style="color: #E5C07B;">address</span><span> =&gt;</span><span style="color: #E5C07B;"> uint</span><span>)</span><span style="color: #C678DD;"> public</span><span> balances;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">35</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">36</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> transfer</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> to</span><span>,</span><span style="color: #E5C07B;"> uint</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>)</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">37</span><span style="color: #C678DD;"> require</span><span>(!paused,</span><span style="color: #98C379;"> &quot;Contract is paused&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">38</span><span> balances[</span><span style="color: #E5C07B;">msg.sender</span><span>]</span><span style="color: #56B6C2;"> -=</span><span> amount;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">39</span><span> balances[to]</span><span style="color: #56B6C2;"> +=</span><span> amount;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">40</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">41</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">42</span><span style="color: #7F848E;font-style: italic;"> // Override to restrict to owner only</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">43</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> pause</span><span>()</span><span style="color: #C678DD;"> public override</span><span style="color: #61AFEF;"> onlyOwner</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">44</span><span style="color: #E5C07B;font-style: italic;"> super</span><span>.</span><span style="color: #61AFEF;">pause</span><span>();</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">45</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">46</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">47</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> unpause</span><span>()</span><span style="color: #C678DD;"> public override</span><span style="color: #61AFEF;"> onlyOwner</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">48</span><span style="color: #E5C07B;font-style: italic;"> super</span><span>.</span><span style="color: #61AFEF;">unpause</span><span>();</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">49</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">50</span><span>}</span></span></code></pre> <p><code>Token</code> inherits <code>owner</code>, <code>onlyOwner</code>, and <code>transferOwnership</code> from <code>Ownable</code>. It inherits <code>paused</code>, <code>pause</code>, and <code>unpause</code> from <code>Pausable</code>. It then narrows the pause functions with the <code>onlyOwner</code> modifier, and uses <code>super</code> to call the original implementations.</p> <h2 id="common-mistakes">Common Mistakes</h2> <p><strong>State variable shadowing.</strong> You cannot declare a state variable in a child with the same name as one in a parent. The compiler will error.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="shadowing.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Parent</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #E5C07B;"> uint</span><span style="color: #C678DD;"> public</span><span> value </span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> 10</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Child</span><span style="color: #C678DD;"> is</span><span style="color: #E5C07B;"> Parent</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #7F848E;font-style: italic;"> // Compiler error: cannot shadow parent&#39;s state variable</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #7F848E;font-style: italic;"> // uint public value = 20;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span>}</span></span></code></pre> <p><strong>Constructor arguments.</strong> Parent constructors run before child constructors. If a parent requires constructor arguments, you must pass them in the child.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="constructor.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Parent</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #E5C07B;"> uint</span><span style="color: #C678DD;"> public</span><span> value;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;"> constructor</span><span>(</span><span style="color: #E5C07B;">uint</span><span style="font-style: italic;"> _value</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span> value </span><span style="color: #56B6C2;">=</span><span> _value;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #7F848E;font-style: italic;">// Pass the argument directly in the inheritance list</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Child</span><span style="color: #C678DD;"> is</span><span style="color: #E5C07B;"> Parent</span><span>(</span><span style="color: #E5C07B;">100</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span style="color: #C678DD;"> constructor</span><span>() {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span style="color: #7F848E;font-style: italic;"> // runs after Parent constructor</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span>}</span></span></code></pre> <p><strong>Visibility.</strong> You can only override <code>public</code> or <code>external</code> functions. <code>private</code> functions are not visible to child contracts at all. <code>internal</code> functions are visible and can be called, but they cannot be marked <code>virtual</code> and overridden unless the parent explicitly allows it.</p> <hr /> <p>Inheritance in Solidity gives you a clean way to separate concerns across contracts and reuse logic without duplication. The four keywords (<code>is</code>, <code>virtual</code>, <code>override</code>, <code>super</code>) each serve a distinct role, and understanding how they interact with multiple inheritance and linearization will save you from confusing compiler errors when contracts get more complex.</p> 2025-11-04T00:00:00+00:00 2025-11-04T00:00:00+00:00 Akash Vaghela https://akash11.com/blog/visibility-in-solidity/ <p>Solidity gives you four visibility modifiers: <code>public</code>, <code>private</code>, <code>internal</code>, and <code>external</code>. They control which code can call a function or read a state variable. Getting them wrong either locks down functionality that should be open, or exposes internals that should stay hidden.</p> <p>This post explains what each modifier does, where it applies, how it interacts with inheritance, and when to reach for each one.</p> <hr /> <h2 id="the-four-modifiers-at-a-glance">The Four Modifiers at a Glance</h2> <table><thead><tr><th>Modifier</th><th>State variables</th><th>Functions</th><th>Who can access</th></tr></thead><tbody> <tr><td><code>public</code></td><td>Yes</td><td>Yes</td><td>Anyone, anywhere</td></tr> <tr><td><code>private</code></td><td>Yes</td><td>Yes</td><td>Current contract only</td></tr> <tr><td><code>internal</code></td><td>Yes (default)</td><td>Yes</td><td>Current contract and derived contracts</td></tr> <tr><td><code>external</code></td><td>No</td><td>Yes</td><td>Outside callers only</td></tr> </tbody></table> <p><code>external</code> cannot be used on state variables. Attempting it will cause a compile error.</p> <hr /> <h2 id="state-variable-visibility">State Variable Visibility</h2> <h3 id="public">public</h3> <p>Declaring a state variable <code>public</code> tells the compiler to generate a getter function automatically. External callers use that getter to read the value. You do not write it yourself.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> VisibilityExample</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #E5C07B;"> uint256</span><span style="color: #C678DD;"> public</span><span> myNumber </span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> 42</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span><span style="color: #7F848E;font-style: italic;"> // Compiler generates: function myNumber() public view returns (uint256)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">4</span><span>}</span></span></code></pre> <p>Any external contract or wallet can call <code>myNumber()</code> and get back <code>42</code>. This is clean and convenient, but only declare variables <code>public</code> if you actually want them readable by anyone.</p> <h3 id="private">private</h3> <p>A <code>private</code> variable can only be accessed by functions inside the same contract. Derived contracts cannot read it, even though they inherit from the same base.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> MyContract</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #E5C07B;"> uint256</span><span style="color: #C678DD;"> private</span><span> secretValue </span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> 100</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> revealSecret</span><span>()</span><span style="color: #C678DD;"> public view returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #C678DD;"> return</span><span> secretValue;</span><span style="color: #7F848E;font-style: italic;"> // allowed</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> ChildContract</span><span style="color: #C678DD;"> is</span><span style="color: #E5C07B;"> MyContract</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> tryAccess</span><span>()</span><span style="color: #C678DD;"> public view returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span style="color: #7F848E;font-style: italic;"> // return secretValue; // compile error</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span style="color: #C678DD;"> return</span><span style="color: #D19A66;"> 0</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span>}</span></span></code></pre> <blockquote class="markdown-alert-warning"> <p><code>private</code> does not hide data from the blockchain. All storage slots are publicly readable by anyone who queries the chain directly. <code>private</code> only prevents other Solidity contracts from referencing the variable by name. Never store sensitive data on-chain and assume <code>private</code> protects it.</p> </blockquote> <h3 id="internal">internal</h3> <p><code>internal</code> is the default visibility for state variables. If you declare a variable without specifying visibility, Solidity treats it as <code>internal</code>. The variable is accessible within the contract and within any contract that inherits from it.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Parent</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #E5C07B;"> uint256</span><span style="color: #C678DD;"> internal</span><span> familySecret </span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> 500</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Child</span><span style="color: #C678DD;"> is</span><span style="color: #E5C07B;"> Parent</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> read</span><span>()</span><span style="color: #C678DD;"> public view returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #C678DD;"> return</span><span> familySecret;</span><span style="color: #7F848E;font-style: italic;"> // allowed</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span>}</span></span></code></pre> <p>Prefer writing <code>internal</code> explicitly rather than relying on the default. It makes intent clear.</p> <hr /> <h2 id="function-visibility">Function Visibility</h2> <h3 id="public-1">public</h3> <p>A <code>public</code> function can be called from inside the contract or from outside. It is the most flexible option, but it has a cost: when called internally, Solidity copies function arguments into memory. For small inputs this does not matter, but for large arrays it adds unnecessary gas overhead.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Calculator</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> add</span><span>(</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> a</span><span>,</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> b</span><span>)</span><span style="color: #C678DD;"> public pure returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #C678DD;"> return</span><span> a </span><span style="color: #56B6C2;">+</span><span> b;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> calculate</span><span>()</span><span style="color: #C678DD;"> public pure returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #C678DD;"> return</span><span style="color: #61AFEF;"> add</span><span>(</span><span style="color: #D19A66;">10</span><span>,</span><span style="color: #D19A66;"> 20</span><span>);</span><span style="color: #7F848E;font-style: italic;"> // internal call to public function</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span>}</span></span></code></pre><h3 id="external">external</h3> <p>An <code>external</code> function can only be called from outside the contract. You cannot call it directly by name from within the same contract. Calling it internally requires <code>this.functionName()</code>, which creates an external call and costs significantly more gas.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> DataProcessor</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> processData</span><span>(</span><span style="color: #E5C07B;">uint256</span><span>[]</span><span style="color: #C678DD;"> calldata</span><span style="color: #E06C75;font-style: italic;"> data</span><span>)</span><span style="color: #C678DD;"> external pure returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #C678DD;"> return</span><span> data.length;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> internalProcess</span><span>()</span><span style="color: #C678DD;"> public pure returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #E5C07B;"> uint256</span><span>[]</span><span style="color: #C678DD;"> memory</span><span> testData </span><span style="color: #56B6C2;">=</span><span style="color: #C678DD;"> new</span><span style="color: #E5C07B;"> uint256</span><span>[](</span><span style="color: #D19A66;">3</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #7F848E;font-style: italic;"> // return processData(testData); // compile error</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #C678DD;"> return</span><span style="color: #E5C07B;"> this</span><span>.</span><span style="color: #61AFEF;">processData</span><span>(testData);</span><span style="color: #7F848E;font-style: italic;"> // works, but expensive</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span>}</span></span></code></pre> <p>The main advantage of <code>external</code> is that it allows <code>calldata</code> for array parameters. <code>calldata</code> is read directly from the transaction input without copying, which is cheaper than loading into memory. If a function only ever gets called from outside and accepts large arrays, <code>external</code> with <code>calldata</code> is the correct choice.</p> <h3 id="internal-1">internal</h3> <p>An <code>internal</code> function is accessible within the contract and in any contract that inherits from it. It is never part of the contract's ABI, so no external caller can invoke it.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Math</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> multiply</span><span>(</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> a</span><span>,</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> b</span><span>)</span><span style="color: #C678DD;"> internal pure returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #C678DD;"> return</span><span> a </span><span style="color: #56B6C2;">*</span><span> b;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> square</span><span>(</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> x</span><span>)</span><span style="color: #C678DD;"> public pure returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #C678DD;"> return</span><span style="color: #61AFEF;"> multiply</span><span>(x, x);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> AdvancedMath</span><span style="color: #C678DD;"> is</span><span style="color: #E5C07B;"> Math</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> cube</span><span>(</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> x</span><span>)</span><span style="color: #C678DD;"> public pure returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span style="color: #C678DD;"> return</span><span style="color: #61AFEF;"> multiply</span><span>(x,</span><span style="color: #61AFEF;"> multiply</span><span>(x, x));</span><span style="color: #7F848E;font-style: italic;"> // inherited, accessible</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span>}</span></span></code></pre> <p>Use <code>internal</code> for helper functions that child contracts may need to reuse. It avoids duplicating logic while keeping the function off the public interface.</p> <h3 id="private-1">private</h3> <p>A <code>private</code> function works the same as <code>internal</code> within the current contract, but derived contracts cannot call it at all.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Secure</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #E5C07B;"> uint256</span><span style="color: #C678DD;"> private</span><span> counter;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> incrementCounter</span><span>()</span><span style="color: #C678DD;"> private</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span> counter</span><span style="color: #56B6C2;">++</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> doSomething</span><span>()</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #61AFEF;"> incrementCounter</span><span>();</span><span style="color: #7F848E;font-style: italic;"> // allowed</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Extended</span><span style="color: #C678DD;"> is</span><span style="color: #E5C07B;"> Secure</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> tryIncrement</span><span>()</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span style="color: #7F848E;font-style: italic;"> // incrementCounter(); // compile error</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">17</span><span>}</span></span></code></pre> <p>Use <code>private</code> when a function is a low-level implementation detail that should never be part of an inheritance interface.</p> <hr /> <h2 id="visibility-across-inheritance">Visibility Across Inheritance</h2> <p>This example shows all four modifiers in one inheritance scenario:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Base</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #E5C07B;"> uint256</span><span style="color: #C678DD;"> public</span><span> publicVar </span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> 1</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #E5C07B;"> uint256</span><span style="color: #C678DD;"> internal</span><span> internalVar </span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> 2</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #E5C07B;"> uint256</span><span style="color: #C678DD;"> private</span><span> privateVar </span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> 3</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> publicFunc</span><span>()</span><span style="color: #C678DD;"> public pure returns</span><span> (</span><span style="color: #E5C07B;">string</span><span style="color: #C678DD;"> memory</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #C678DD;"> return</span><span style="color: #98C379;"> &quot;public&quot;</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> internalFunc</span><span>()</span><span style="color: #C678DD;"> internal pure returns</span><span> (</span><span style="color: #E5C07B;">string</span><span style="color: #C678DD;"> memory</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span style="color: #C678DD;"> return</span><span style="color: #98C379;"> &quot;internal&quot;</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> privateFunc</span><span>()</span><span style="color: #C678DD;"> private pure returns</span><span> (</span><span style="color: #E5C07B;">string</span><span style="color: #C678DD;"> memory</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span style="color: #C678DD;"> return</span><span style="color: #98C379;"> &quot;private&quot;</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">17</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">18</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">19</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Derived</span><span style="color: #C678DD;"> is</span><span style="color: #E5C07B;"> Base</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">20</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> testAccess</span><span>()</span><span style="color: #C678DD;"> public view returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">21</span><span style="color: #E5C07B;"> uint256</span><span> sum </span><span style="color: #56B6C2;">=</span><span> publicVar </span><span style="color: #56B6C2;">+</span><span> internalVar;</span><span style="color: #7F848E;font-style: italic;"> // both accessible</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">22</span><span style="color: #7F848E;font-style: italic;"> // uint256 bad = privateVar; // compile error</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">23</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">24</span><span style="color: #61AFEF;"> publicFunc</span><span>();</span><span style="color: #7F848E;font-style: italic;"> // accessible</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">25</span><span style="color: #61AFEF;"> internalFunc</span><span>();</span><span style="color: #7F848E;font-style: italic;"> // accessible</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">26</span><span style="color: #7F848E;font-style: italic;"> // privateFunc(); // compile error</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">27</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">28</span><span style="color: #C678DD;"> return</span><span> sum;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">29</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">30</span><span>}</span></span></code></pre> <p>Derived contracts inherit <code>public</code> and <code>internal</code> members. They never get access to <code>private</code> members. This is a hard boundary enforced at compile time.</p> <hr /> <h2 id="practical-guidelines">Practical Guidelines</h2> <p><strong>Default to the most restrictive option.</strong> Start with <code>private</code>. Move to <code>internal</code> if child contracts need access. Move to <code>public</code> or <code>external</code> only if outside callers need it.</p> <p><strong>Use <code>external</code> for functions that only serve outside callers.</strong> Especially if those functions accept array parameters. The <code>calldata</code> keyword saves gas and <code>external</code> makes the intent explicit.</p> <p><strong>Use <code>internal</code> for shared helpers in a contract family.</strong> It is cleaner than duplicating logic or making everything <code>public</code>.</p> <p><strong>Do not treat <code>private</code> as encryption.</strong> All on-chain state is readable. Use <code>private</code> for access control at the Solidity level, not for data confidentiality.</p> <p><strong>Let the compiler generate getters.</strong> Public state variables get their getter for free. Only write a custom getter if you need to transform or filter the output.</p> <hr /> <h2 id="common-mistakes">Common Mistakes</h2> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="mistakes.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Mistakes</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #7F848E;font-style: italic;"> // Mistake 1: public when internal would work</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #7F848E;font-style: italic;"> // Nothing outside this contract reads helperValue</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #E5C07B;"> uint256</span><span style="color: #C678DD;"> public</span><span> helperValue;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #7F848E;font-style: italic;"> // Mistake 2: public when external would work</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #7F848E;font-style: italic;"> // This function is never called internally</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #7F848E;font-style: italic;"> // Switching to external with calldata saves gas</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> processArray</span><span>(</span><span style="color: #E5C07B;">uint256</span><span>[]</span><span style="color: #C678DD;"> memory</span><span style="color: #E06C75;font-style: italic;"> data</span><span>)</span><span style="color: #C678DD;"> public pure returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #C678DD;"> return</span><span> data.length;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span style="color: #7F848E;font-style: italic;"> // Mistake 3: missing visibility on a function</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span style="color: #7F848E;font-style: italic;"> // Default for functions is internal, not public</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span style="color: #7F848E;font-style: italic;"> // This function is not callable externally</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> oops</span><span>()</span><span style="color: #C678DD;"> pure returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">17</span><span style="color: #C678DD;"> return</span><span style="color: #D19A66;"> 42</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">18</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">19</span><span>}</span></span></code></pre> <p>The third mistake is subtle. State variables default to <code>internal</code>, but functions also default to <code>internal</code> if you omit the modifier. A function without visibility is invisible to external callers, which may not be what you intended. Always write visibility explicitly on functions.</p> <hr /> <h2 id="visibility-and-attack-surface">Visibility and Attack Surface</h2> <p>Every <code>public</code> or <code>external</code> function is an entry point into your contract. Unnecessary exposure increases the number of ways an attacker can interact with your code.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="secure.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> SecureExample</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;"> mapping</span><span>(</span><span style="color: #E5C07B;">address</span><span> =&gt;</span><span style="color: #E5C07B;"> uint256</span><span>)</span><span style="color: #C678DD;"> private</span><span> balances;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> deposit</span><span>()</span><span style="color: #C678DD;"> external payable</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span> balances[</span><span style="color: #E5C07B;">msg.sender</span><span>]</span><span style="color: #56B6C2;"> +=</span><span style="color: #E5C07B;"> msg</span><span>.value;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #7F848E;font-style: italic;"> // Private: only used internally, not part of the ABI</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> updateBalance</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> user</span><span>,</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>)</span><span style="color: #C678DD;"> private</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span> balances[user]</span><span style="color: #56B6C2;"> =</span><span> amount;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span style="color: #7F848E;font-style: italic;"> // External: read-only, only exposes the caller&#39;s own balance</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> getBalance</span><span>()</span><span style="color: #C678DD;"> external view returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span style="color: #C678DD;"> return</span><span> balances[</span><span style="color: #E5C07B;">msg.sender</span><span>];</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">17</span><span>}</span></span></code></pre> <p>The <code>balances</code> mapping is <code>private</code>. The <code>updateBalance</code> helper is <code>private</code>. The only entry points are <code>deposit</code> and <code>getBalance</code>. This is the smallest possible attack surface for this functionality.</p> <p>Keeping functions <code>private</code> or <code>internal</code> until you have a reason to expose them is a habit that pays off in audit findings and in production.</p> <hr /> <p>Visibility modifiers are straightforward once you understand what each one controls. The rule is simple: expose only what needs to be exposed, and be explicit about every choice. A contract where every variable and function has a deliberate visibility modifier is easier to audit, easier to extend, and harder to exploit.</p> 2025-11-03T00:00:00+00:00 2025-11-03T00:00:00+00:00 Akash Vaghela https://akash11.com/blog/solidity-data-locations-storage-memory-calldata/ <p>Every variable in Solidity lives somewhere. That somewhere is called a data location, and Solidity gives you three: <code>storage</code>, <code>memory</code>, and <code>calldata</code>. Getting this right matters. The wrong location can silently break your contract by updating a copy instead of the real state, or waste gas on unnecessary data copying.</p> <p>This post covers how each location works, when to use each one, and the specific rules that apply to state variables, function parameters, local variables, and return values.</p> <hr /> <h2 id="the-three-locations">The Three Locations</h2> <p><strong><code>storage</code></strong> is persistent. It lives on the blockchain and survives between function calls. Every state variable in your contract lives in storage.</p> <p><strong><code>memory</code></strong> is temporary. It exists only while a function is executing. Once the function returns, memory is gone.</p> <p><strong><code>calldata</code></strong> is read-only. When someone calls an external function, the arguments arrive in calldata. You cannot modify calldata. You can only read from it.</p> <p>The location you choose affects three things: gas cost, whether you can modify the data, and how long the data exists.</p> <hr /> <h2 id="state-variables">State Variables</h2> <p>State variables are declared at the contract level, outside of any function. They always live in <code>storage</code>. You never add a location keyword to a state variable.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> TokenRegistry</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #E5C07B;"> uint256</span><span style="color: #C678DD;"> public</span><span> totalSupply;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #E5C07B;"> address</span><span style="color: #C678DD;"> public</span><span> owner;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #E5C07B;"> string</span><span style="color: #C678DD;"> public</span><span> name;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #E5C07B;"> uint256</span><span>[]</span><span style="color: #C678DD;"> public</span><span> allIds;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #C678DD;"> mapping</span><span>(</span><span style="color: #E5C07B;">address</span><span> =&gt;</span><span style="color: #E5C07B;"> uint256</span><span>)</span><span style="color: #C678DD;"> public</span><span> balances;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #C678DD;"> struct</span><span style="color: #E5C07B;"> Token</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #E5C07B;"> uint256</span><span> id;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #E5C07B;"> string</span><span> name;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span style="color: #E5C07B;"> address</span><span> owner;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span> Token[]</span><span style="color: #C678DD;"> public</span><span> tokens;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span>}</span></span></code></pre> <p>Adding a location keyword to a state variable is a compile error:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #7F848E;font-style: italic;">// This will not compile</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #E5C07B;">uint256</span><span style="color: #C678DD;"> memory</span><span> counter;</span></span></code></pre> <p>State variables are <code>storage</code> by definition. The keyword is not allowed and not needed.</p> <hr /> <h2 id="value-types-vs-reference-types">Value Types vs Reference Types</h2> <p>Before looking at function variables and parameters, you need to understand one distinction: value types vs reference types.</p> <p><strong>Value types</strong> include <code>uint</code>, <code>int</code>, <code>bool</code>, <code>address</code>, <code>bytes1</code> through <code>bytes32</code>, and enums. When you assign a value type, Solidity copies it. There is no "reference" to the original. Because of this, value types never need a location keyword.</p> <p><strong>Reference types</strong> include arrays, structs, strings, and <code>bytes</code>. When you assign a reference type, it can either point to the original or be a new copy, depending on the location you specify. This is where the choice matters.</p> <hr /> <h2 id="local-variables-inside-functions">Local Variables Inside Functions</h2> <p>When you declare a local variable of a reference type inside a function, you must choose <code>storage</code> or <code>memory</code>.</p> <h3 id="storage-gives-you-a-reference">storage gives you a reference</h3> <p>Using <code>storage</code> creates a pointer to a state variable. Changes through that pointer modify the actual state.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Example</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #E5C07B;"> uint256</span><span>[]</span><span style="color: #C678DD;"> public</span><span> numbers;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> addToState</span><span>()</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #7F848E;font-style: italic;"> // storageRef points to the state variable &#39;numbers&#39;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #E5C07B;"> uint256</span><span>[]</span><span style="color: #C678DD;"> storage</span><span> storageRef </span><span style="color: #56B6C2;">=</span><span> numbers;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span> storageRef.</span><span style="color: #61AFEF;">push</span><span>(</span><span style="color: #D19A66;">42</span><span>);</span><span style="color: #7F848E;font-style: italic;"> // This modifies &#39;numbers&#39; in state</span></span> <span class="giallo-l" style="background-color: #2C313C;"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span> }</span></span> <span class="giallo-l" style="background-color: #2C313C;"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span>}</span></span></code></pre><h3 id="memory-gives-you-a-copy">memory gives you a copy</h3> <p>Using <code>memory</code> creates a temporary copy of the data. Changes to it do not touch the state variable.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Example</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #E5C07B;"> uint256</span><span>[]</span><span style="color: #C678DD;"> public</span><span> numbers;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> readOnly</span><span>()</span><span style="color: #C678DD;"> public view</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #7F848E;font-style: italic;"> // memoryCopy is a separate copy, changes here go nowhere</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #E5C07B;"> uint256</span><span>[]</span><span style="color: #C678DD;"> memory</span><span> memoryCopy </span><span style="color: #56B6C2;">=</span><span> numbers;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span> memoryCopy[</span><span style="color: #D19A66;">0</span><span>]</span><span style="color: #56B6C2;"> =</span><span style="color: #D19A66;"> 999</span><span>;</span><span style="color: #7F848E;font-style: italic;"> // Only modifies the local copy</span></span> <span class="giallo-l" style="background-color: #2C313C;"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span> }</span></span> <span class="giallo-l" style="background-color: #2C313C;"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span>}</span></span></code></pre> <p>The same rule applies to structs:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Example</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;"> struct</span><span style="color: #E5C07B;"> Person</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #E5C07B;"> string</span><span> name;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #E5C07B;"> uint256</span><span> age;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span> Person </span><span style="color: #C678DD;">public</span><span> person;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> updateAge</span><span>()</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #7F848E;font-style: italic;"> // Wrong: creates a copy, state is unchanged</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span> Person </span><span style="color: #C678DD;">memory</span><span> copy </span><span style="color: #56B6C2;">=</span><span> person;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span> copy.age </span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> 30</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span style="color: #7F848E;font-style: italic;"> // Correct: storage reference, state is updated</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span> Person </span><span style="color: #C678DD;">storage</span><span> ref </span><span style="color: #56B6C2;">=</span><span> person;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span> ref.age </span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> 30</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">17</span><span>}</span></span></code></pre> <blockquote class="markdown-alert-warning"> <p>Using <code>memory</code> when you meant <code>storage</code> is a silent bug. The compiler will not warn you. The function will run, the copy will be modified, and the state variable will remain unchanged. Always double-check which one you need before writing a local reference type variable.</p> </blockquote> <h3 id="creating-new-data-in-memory">Creating new data in memory</h3> <p>When you create a new array or struct inside a function, it always goes in <code>memory</code>:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> buildArray</span><span>()</span><span style="color: #C678DD;"> public pure returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>[]</span><span style="color: #C678DD;"> memory</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #E5C07B;"> uint256</span><span>[]</span><span style="color: #C678DD;"> memory</span><span> result </span><span style="color: #56B6C2;">=</span><span style="color: #C678DD;"> new</span><span style="color: #E5C07B;"> uint256</span><span>[](</span><span style="color: #D19A66;">3</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span><span> result[</span><span style="color: #D19A66;">0</span><span>]</span><span style="color: #56B6C2;"> =</span><span style="color: #D19A66;"> 10</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">4</span><span> result[</span><span style="color: #D19A66;">1</span><span>]</span><span style="color: #56B6C2;"> =</span><span style="color: #D19A66;"> 20</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">5</span><span> result[</span><span style="color: #D19A66;">2</span><span>]</span><span style="color: #56B6C2;"> =</span><span style="color: #D19A66;"> 30</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">6</span><span style="color: #C678DD;"> return</span><span> result;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">7</span><span>}</span></span></code></pre> <p>Value types in local variables need no location keyword:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> calculate</span><span>()</span><span style="color: #C678DD;"> public view returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #E5C07B;"> uint256</span><span> total </span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> 0</span><span>;</span><span style="color: #7F848E;font-style: italic;"> // No keyword needed</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span><span style="color: #E5C07B;"> bool</span><span> found </span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> false</span><span>;</span><span style="color: #7F848E;font-style: italic;"> // No keyword needed</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">4</span><span style="color: #E5C07B;"> address</span><span> sender </span><span style="color: #56B6C2;">=</span><span style="color: #E5C07B;"> msg.sender</span><span>;</span><span style="color: #7F848E;font-style: italic;"> // No keyword needed</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">5</span><span style="color: #C678DD;"> return</span><span> total;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">6</span><span>}</span></span></code></pre> <hr /> <h2 id="function-parameters">Function Parameters</h2> <p>The right location for a function parameter depends on the function visibility and whether you need to modify the data.</p> <h3 id="external-functions-use-calldata">External functions: use calldata</h3> <p>External functions can only be called from outside the contract. For reference type parameters, <code>calldata</code> is the most efficient choice. The data arrives in calldata already, so using <code>calldata</code> means no copying.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> TokenRegistry</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;"> struct</span><span style="color: #E5C07B;"> Token</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #E5C07B;"> uint256</span><span> id;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #E5C07B;"> string</span><span> name;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #E5C07B;"> address</span><span> owner;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> registerTokens</span><span>(</span><span style="color: #C678DD;">Token</span><span>[]</span><span style="color: #C678DD;"> calldata</span><span style="color: #E06C75;font-style: italic;"> newTokens</span><span>)</span><span style="color: #C678DD;"> external</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #C678DD;"> for</span><span> (</span><span style="color: #E5C07B;">uint256</span><span> i </span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> 0</span><span>; i &lt; newTokens.length; i</span><span style="color: #56B6C2;">++</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #7F848E;font-style: italic;"> // Reading from calldata is cheap</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span style="color: #7F848E;font-style: italic;"> // Cannot modify newTokens[i] directly</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> getNameLength</span><span>(</span><span style="color: #E5C07B;">string</span><span style="color: #C678DD;"> calldata</span><span style="color: #E06C75;font-style: italic;"> name</span><span>)</span><span style="color: #C678DD;"> external pure returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span style="color: #C678DD;"> return</span><span style="color: #E5C07B;"> bytes</span><span>(name).length;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">17</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">18</span><span>}</span></span></code></pre> <p>Because <code>calldata</code> is read-only, you cannot modify the parameter. If you need to modify the data inside the function, copy it to memory first.</p> <h3 id="public-functions-calldata-or-memory">Public functions: calldata or memory</h3> <p>Public functions can be called externally or from within the contract. Both <code>calldata</code> and <code>memory</code> are valid for reference type parameters.</p> <p><code>calldata</code> costs less gas when called externally. <code>memory</code> is required when the function is called internally, since internal calls cannot pass calldata directly.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Example</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #7F848E;font-style: italic;"> // Works, but costs more gas when called externally</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> withMemory</span><span>(</span><span style="color: #E5C07B;">uint256</span><span>[]</span><span style="color: #C678DD;"> memory</span><span style="color: #E06C75;font-style: italic;"> data</span><span>)</span><span style="color: #C678DD;"> public pure returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;"> return</span><span> data.length;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #7F848E;font-style: italic;"> // More efficient for external callers</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> withCalldata</span><span>(</span><span style="color: #E5C07B;">uint256</span><span>[]</span><span style="color: #C678DD;"> calldata</span><span style="color: #E06C75;font-style: italic;"> data</span><span>)</span><span style="color: #C678DD;"> public pure returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #C678DD;"> return</span><span> data.length;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span>}</span></span></code></pre> <p>For <code>public</code> functions that are called mostly externally, prefer <code>calldata</code>. For functions that are also called internally, <code>memory</code> is the safer default.</p> <h3 id="internal-and-private-functions-memory-or-storage">Internal and private functions: memory or storage</h3> <p>Internal and private functions cannot be called from outside the contract. You can pass either a <code>memory</code> copy or a <code>storage</code> reference.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Example</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #E5C07B;"> uint256</span><span>[]</span><span style="color: #C678DD;"> public</span><span> numbers;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #7F848E;font-style: italic;"> // Internal function that modifies state via storage reference</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> addToArray</span><span>(</span><span style="color: #E5C07B;">uint256</span><span>[]</span><span style="color: #C678DD;"> storage</span><span style="color: #E06C75;font-style: italic;"> arr</span><span>,</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> value</span><span>)</span><span style="color: #C678DD;"> internal</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span> arr.</span><span style="color: #61AFEF;">push</span><span>(value);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #7F848E;font-style: italic;"> // Internal function that reads from a memory array</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> sumArray</span><span>(</span><span style="color: #E5C07B;">uint256</span><span>[]</span><span style="color: #C678DD;"> memory</span><span style="color: #E06C75;font-style: italic;"> arr</span><span>)</span><span style="color: #C678DD;"> internal pure returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span style="color: #E5C07B;"> uint256</span><span> total </span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> 0</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span style="color: #C678DD;"> for</span><span> (</span><span style="color: #E5C07B;">uint256</span><span> i </span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> 0</span><span>; i &lt; arr.length; i</span><span style="color: #56B6C2;">++</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span> total </span><span style="color: #56B6C2;">+=</span><span> arr[i];</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span style="color: #C678DD;"> return</span><span> total;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">17</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">18</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> run</span><span>()</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">19</span><span style="color: #61AFEF;"> addToArray</span><span>(numbers,</span><span style="color: #D19A66;"> 100</span><span>);</span><span style="color: #7F848E;font-style: italic;"> // Passes storage reference</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">20</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">21</span><span style="color: #E5C07B;"> uint256</span><span>[]</span><span style="color: #C678DD;"> memory</span><span> temp </span><span style="color: #56B6C2;">=</span><span style="color: #C678DD;"> new</span><span style="color: #E5C07B;"> uint256</span><span>[](</span><span style="color: #D19A66;">3</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">22</span><span> temp[</span><span style="color: #D19A66;">0</span><span>]</span><span style="color: #56B6C2;"> =</span><span style="color: #D19A66;"> 1</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">23</span><span> temp[</span><span style="color: #D19A66;">1</span><span>]</span><span style="color: #56B6C2;"> =</span><span style="color: #D19A66;"> 2</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">24</span><span> temp[</span><span style="color: #D19A66;">2</span><span>]</span><span style="color: #56B6C2;"> =</span><span style="color: #D19A66;"> 3</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">25</span><span style="color: #E5C07B;"> uint256</span><span> result </span><span style="color: #56B6C2;">=</span><span style="color: #61AFEF;"> sumArray</span><span>(temp);</span><span style="color: #7F848E;font-style: italic;"> // Passes memory array</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">26</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">27</span><span>}</span></span></code></pre> <p>Value type parameters never take a location keyword, regardless of function visibility:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #7F848E;font-style: italic;">// Correct</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> transfer</span><span>(</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>,</span><span style="color: #E5C07B;"> address</span><span style="color: #E06C75;font-style: italic;"> to</span><span>,</span><span style="color: #E5C07B;"> bool</span><span style="color: #E06C75;font-style: italic;"> verified</span><span>)</span><span style="color: #C678DD;"> public</span><span> { }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">4</span><span style="color: #7F848E;font-style: italic;">// Compile error</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">5</span><span style="color: #7F848E;font-style: italic;">// function transfer(uint256 memory amount) public { }</span></span></code></pre> <hr /> <h2 id="return-values">Return Values</h2> <p>Value types returned from functions need no location keyword. Reference types must use <code>memory</code> or <code>calldata</code>. You cannot return a <code>storage</code> reference.</p> <h3 id="returning-reference-types-from-state">Returning reference types from state</h3> <p>When a function returns an array or struct from state, Solidity copies it into memory first:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Example</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #E5C07B;"> uint256</span><span>[]</span><span style="color: #C678DD;"> public</span><span> numbers;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #E5C07B;"> string</span><span style="color: #C678DD;"> public</span><span> text;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> getNumbers</span><span>()</span><span style="color: #C678DD;"> public view returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>[]</span><span style="color: #C678DD;"> memory</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #C678DD;"> return</span><span> numbers;</span><span style="color: #7F848E;font-style: italic;"> // Copied from storage to memory</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> getText</span><span>()</span><span style="color: #C678DD;"> public view returns</span><span> (</span><span style="color: #E5C07B;">string</span><span style="color: #C678DD;"> memory</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #C678DD;"> return</span><span> text;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span>}</span></span></code></pre><h3 id="returning-newly-created-data">Returning newly created data</h3> <p>When you create data inside a function and return it, it must be <code>memory</code>:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> buildRange</span><span>(</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> n</span><span>)</span><span style="color: #C678DD;"> public pure returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>[]</span><span style="color: #C678DD;"> memory</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #E5C07B;"> uint256</span><span>[]</span><span style="color: #C678DD;"> memory</span><span> result </span><span style="color: #56B6C2;">=</span><span style="color: #C678DD;"> new</span><span style="color: #E5C07B;"> uint256</span><span>[](</span><span style="color: #E06C75;font-style: italic;">n</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span><span style="color: #C678DD;"> for</span><span> (</span><span style="color: #E5C07B;">uint256</span><span> i </span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> 0</span><span>; i &lt; n; i</span><span style="color: #56B6C2;">++</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">4</span><span> result[i]</span><span style="color: #56B6C2;"> =</span><span> i;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">5</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">6</span><span style="color: #C678DD;"> return</span><span> result;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">7</span><span>}</span></span></code></pre><h3 id="returning-calldata-directly">Returning calldata directly</h3> <p>If a function receives a <code>calldata</code> parameter and you want to return it unchanged, you can return <code>calldata</code> directly. This avoids copying and saves gas:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> passThrough</span><span>(</span><span style="color: #E5C07B;">string</span><span style="color: #C678DD;"> calldata</span><span style="color: #E06C75;font-style: italic;"> input</span><span>)</span><span style="color: #C678DD;"> external pure returns</span><span> (</span><span style="color: #E5C07B;">string</span><span style="color: #C678DD;"> calldata</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #C678DD;"> return</span><span> input;</span><span style="color: #7F848E;font-style: italic;"> // No copy, very efficient</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span><span>}</span></span></code></pre> <p>This only works when you return the same calldata without modification.</p> <hr /> <h2 id="a-full-example">A Full Example</h2> <p>Here is a contract that uses all three locations together, showing how they interact:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="TokenRegistry.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #7F848E;font-style: italic;">// SPDX-License-Identifier: MIT</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;">pragma</span><span style="color: #E06C75;"> solidity</span><span style="color: #D19A66;"> ^0.8.0</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> TokenRegistry</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #7F848E;font-style: italic;"> // State variables: always storage, no keyword</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #E5C07B;"> address</span><span style="color: #C678DD;"> public</span><span> owner;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #E5C07B;"> uint256</span><span style="color: #C678DD;"> public</span><span> totalCount;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #C678DD;"> struct</span><span style="color: #E5C07B;"> Token</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #E5C07B;"> uint256</span><span> id;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span style="color: #E5C07B;"> string</span><span> name;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span style="color: #E5C07B;"> address</span><span> tokenOwner;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span> Token[]</span><span style="color: #C678DD;"> public</span><span> tokens;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span style="color: #C678DD;"> mapping</span><span>(</span><span style="color: #E5C07B;">address</span><span> =&gt;</span><span style="color: #E5C07B;"> uint256</span><span>[])</span><span style="color: #C678DD;"> public</span><span> ownerTokenIds;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">17</span><span style="color: #C678DD;"> constructor</span><span>() {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">18</span><span> owner </span><span style="color: #56B6C2;">=</span><span style="color: #E5C07B;"> msg.sender</span><span>;</span><span style="color: #7F848E;font-style: italic;"> // value type, no keyword</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">19</span><span> totalCount </span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> 0</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">20</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">21</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">22</span><span style="color: #7F848E;font-style: italic;"> // External: calldata for reference types</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">23</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> batchRegister</span><span>(</span><span style="color: #C678DD;">Token</span><span>[]</span><span style="color: #C678DD;"> calldata</span><span style="color: #E06C75;font-style: italic;"> newTokens</span><span>)</span><span style="color: #C678DD;"> external</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">24</span><span style="color: #C678DD;"> require</span><span>(</span><span style="color: #E5C07B;">msg.sender</span><span> == owner,</span><span style="color: #98C379;"> &quot;Not owner&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">25</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">26</span><span style="color: #C678DD;"> for</span><span> (</span><span style="color: #E5C07B;">uint256</span><span> i </span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> 0</span><span>; i &lt; newTokens.length; i</span><span style="color: #56B6C2;">++</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">27</span><span> tokens.</span><span style="color: #61AFEF;">push</span><span>(newTokens[i]);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">28</span><span> ownerTokenIds[newTokens[i].tokenOwner].</span><span style="color: #61AFEF;">push</span><span>(newTokens[i].id);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">29</span><span> totalCount</span><span style="color: #56B6C2;">++</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">30</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">31</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">32</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">33</span><span style="color: #7F848E;font-style: italic;"> // Public: returns memory copy from state</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">34</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> getToken</span><span>(</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> index</span><span>)</span><span style="color: #C678DD;"> public view returns</span><span> (</span><span style="color: #C678DD;">Token memory</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">35</span><span style="color: #C678DD;"> return</span><span> tokens[index];</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">36</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">37</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">38</span><span style="color: #7F848E;font-style: italic;"> // Internal: storage reference to modify state directly</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">39</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> updateName</span><span>(</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> index</span><span>,</span><span style="color: #E5C07B;"> string</span><span style="color: #C678DD;"> memory</span><span style="color: #E06C75;font-style: italic;"> newName</span><span>)</span><span style="color: #C678DD;"> internal</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">40</span><span> Token </span><span style="color: #C678DD;">storage</span><span> token </span><span style="color: #56B6C2;">=</span><span> tokens[index];</span><span style="color: #7F848E;font-style: italic;"> // storage reference</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">41</span><span> token.name </span><span style="color: #56B6C2;">=</span><span> newName;</span><span style="color: #7F848E;font-style: italic;"> // modifies state</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">42</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">43</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">44</span><span style="color: #7F848E;font-style: italic;"> // Internal: pure calculation using memory</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">45</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> sumIds</span><span>(</span><span style="color: #E5C07B;">uint256</span><span>[]</span><span style="color: #C678DD;"> memory</span><span style="color: #E06C75;font-style: italic;"> ids</span><span>)</span><span style="color: #C678DD;"> internal pure returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">46</span><span style="color: #E5C07B;"> uint256</span><span> total </span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> 0</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">47</span><span style="color: #C678DD;"> for</span><span> (</span><span style="color: #E5C07B;">uint256</span><span> i </span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> 0</span><span>; i &lt; ids.length; i</span><span style="color: #56B6C2;">++</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">48</span><span> total </span><span style="color: #56B6C2;">+=</span><span> ids[i];</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">49</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">50</span><span style="color: #C678DD;"> return</span><span> total;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">51</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">52</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">53</span><span style="color: #7F848E;font-style: italic;"> // Public: mixes calldata input with storage and memory</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">54</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> processAndUpdate</span><span>(</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">55</span><span style="color: #E5C07B;"> uint256</span><span>[]</span><span style="color: #C678DD;"> calldata</span><span style="color: #E06C75;font-style: italic;"> inputIds</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">56</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> updateIndex</span><span>,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">57</span><span style="color: #E5C07B;"> string</span><span style="color: #C678DD;"> memory</span><span style="color: #E06C75;font-style: italic;"> newName</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">58</span><span> )</span><span style="color: #C678DD;"> public returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">59</span><span style="color: #7F848E;font-style: italic;"> // Work with storage</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">60</span><span style="color: #E5C07B;"> uint256</span><span>[]</span><span style="color: #C678DD;"> storage</span><span> ownerIds </span><span style="color: #56B6C2;">=</span><span> ownerTokenIds[</span><span style="color: #E5C07B;">msg.sender</span><span>];</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">61</span><span> ownerIds.</span><span style="color: #61AFEF;">push</span><span>(inputIds[</span><span style="color: #D19A66;">0</span><span>]);</span><span style="color: #7F848E;font-style: italic;"> // modifies state</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">62</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">63</span><span style="color: #7F848E;font-style: italic;"> // Work with memory</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">64</span><span style="color: #E5C07B;"> uint256</span><span>[]</span><span style="color: #C678DD;"> memory</span><span> tempIds </span><span style="color: #56B6C2;">=</span><span style="color: #C678DD;"> new</span><span style="color: #E5C07B;"> uint256</span><span>[](</span><span style="color: #E06C75;font-style: italic;">inputIds</span><span>.</span><span style="color: #E06C75;font-style: italic;">length</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">65</span><span style="color: #C678DD;"> for</span><span> (</span><span style="color: #E5C07B;">uint256</span><span> i </span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> 0</span><span>; i &lt; inputIds.length; i</span><span style="color: #56B6C2;">++</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">66</span><span> tempIds[i]</span><span style="color: #56B6C2;"> =</span><span> inputIds[i];</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">67</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">68</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">69</span><span style="color: #61AFEF;"> updateName</span><span>(updateIndex, newName);</span><span style="color: #7F848E;font-style: italic;"> // passes memory string to internal</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">70</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">71</span><span style="color: #C678DD;"> return</span><span style="color: #61AFEF;"> sumIds</span><span>(tempIds);</span><span style="color: #7F848E;font-style: italic;"> // passes memory array</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">72</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">73</span><span>}</span></span></code></pre> <hr /> <h2 id="quick-reference">Quick Reference</h2> <table><thead><tr><th>Context</th><th>Value types</th><th>Reference types</th></tr></thead><tbody> <tr><td>State variables</td><td>No keyword (always <code>storage</code>)</td><td>No keyword (always <code>storage</code>)</td></tr> <tr><td>Local variable pointing to state</td><td>No keyword</td><td><code>storage</code></td></tr> <tr><td>Local variable for temporary use</td><td>No keyword</td><td><code>memory</code></td></tr> <tr><td>External function parameter</td><td>No keyword</td><td><code>calldata</code> (preferred)</td></tr> <tr><td>Public function parameter</td><td>No keyword</td><td><code>calldata</code> or <code>memory</code></td></tr> <tr><td>Internal/private function parameter</td><td>No keyword</td><td><code>memory</code> or <code>storage</code></td></tr> <tr><td>Return value</td><td>No keyword</td><td><code>memory</code> or <code>calldata</code></td></tr> </tbody></table> <p>The pattern is consistent once you see it. Value types are always copied, so location never applies to them. Reference types need a location whenever they appear as local variables, parameters, or return values, because Solidity needs to know whether to create a reference or a copy.</p> <p>Use <code>storage</code> when you need to modify state. Use <code>calldata</code> for external inputs you will not modify. Use <code>memory</code> for everything else.</p> 2025-11-01T00:00:00+00:00 2025-11-01T00:00:00+00:00 Akash Vaghela https://akash11.com/blog/gas-and-gas-price-in-solidity/ <p>Gas is the unit that measures computational effort on the Ethereum network. Every operation your smart contract performs costs gas, and gas costs real money paid in ETH. If your contract is inefficient, it becomes expensive for users to interact with. During periods of network congestion, the same transaction can cost 10x more than during quiet periods.</p> <p>This post explains how gas works, how to set gas limits correctly, and how to cut storage costs using variable packing.</p> <h2 id="what-is-gas-and-how-is-cost-calculated">What is Gas and How is Cost Calculated</h2> <p>Every time a user calls a function or deploys a contract, the EVM executes your code across thousands of nodes. Those nodes need compensation for their work. Gas is how that compensation is measured and charged.</p> <p>The formula is simple:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="plain"><span class="giallo-l"><span>Transaction Cost = Gas Used x Gas Price</span></span></code></pre> <p>Gas price is measured in gwei. One gwei equals 0.000000001 ETH. During peak network usage, gas prices can swing from 20 gwei to 200 gwei or higher. The same operation that costs $2 at 20 gwei can cost $20 at 200 gwei.</p> <p>Not all operations cost the same amount of gas. Here is a rough breakdown of common EVM operations:</p> <table><thead><tr><th>Operation</th><th>Gas Cost</th></tr></thead><tbody> <tr><td>Basic arithmetic</td><td>3 gas</td></tr> <tr><td>Reading from storage (cold)</td><td>2100 gas</td></tr> <tr><td>Writing to storage (new value)</td><td>20000 gas</td></tr> <tr><td>Writing to storage (update)</td><td>5000 gas</td></tr> <tr><td>Event emission</td><td>~375 gas per topic</td></tr> </tbody></table> <p>Storage operations are by far the most expensive. Designing your contract to minimize storage reads and writes is the single most impactful optimization you can make.</p> <h2 id="how-gas-limits-work">How Gas Limits Work</h2> <p>The gas limit is the maximum gas you are willing to spend on a transaction. It exists to protect you from runaway execution. Without a limit, a bug causing an infinite loop would drain your wallet completely.</p> <p>There are two kinds of gas limits you need to understand:</p> <p><strong>Block gas limit</strong> is set by the network's validators. It caps the total gas allowed across all transactions in one block. On Ethereum mainnet this is around 30 million gas. It determines how many transactions can fit in a block.</p> <p><strong>Transaction gas limit</strong> is the value you set when sending a transaction. This is what you control.</p> <p>Here is exactly what happens when you submit a transaction:</p> <ol> <li>You set a gas limit (say, 100000 gas)</li> <li>You set a gas price (say, 50 gwei)</li> <li>Your wallet reserves 100000 x 50 = 5000000 gwei (0.005 ETH)</li> <li>The transaction executes and uses actual gas (say, 65000)</li> <li>You pay for 65000 x 50 = 3250000 gwei (0.00325 ETH)</li> <li>The remaining 35000 gas is refunded</li> </ol> <p>The important thing to understand: if your transaction runs out of gas before completing, the EVM reverts all state changes but you do not get the gas back. You pay for the work done up to the point of failure.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> GasLimitDemo</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #E5C07B;"> uint</span><span>[]</span><span style="color: #C678DD;"> public</span><span> numbers;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #7F848E;font-style: italic;"> // Gas cost grows with each iteration</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #7F848E;font-style: italic;"> // Calling addNumbers(1000) needs far more gas than addNumbers(10)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> addNumbers</span><span>(</span><span style="color: #E5C07B;">uint</span><span style="color: #E06C75;font-style: italic;"> count</span><span>)</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #C678DD;"> for</span><span> (</span><span style="color: #E5C07B;">uint</span><span> i </span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> 0</span><span>; i &lt; count; i</span><span style="color: #56B6C2;">++</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span> numbers.</span><span style="color: #61AFEF;">push</span><span>(i);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span>}</span></span></code></pre> <p>If you call <code>addNumbers(1000)</code> with a gas limit of 100000 but the function needs 500000 gas, the transaction fails at the limit, all changes revert, and you pay for the gas consumed up to 100000.</p> <blockquote class="markdown-alert-warning"> <p>Failed transactions still cost gas. Setting the gas limit too low does not save money. It wastes money on failed attempts while leaving state unchanged.</p> </blockquote> <h3 id="setting-the-right-gas-limit">Setting the Right Gas Limit</h3> <p>Most wallets estimate gas automatically, but their estimates can be wrong for complex or loop-heavy functions. You can add a safety buffer in your scripts:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="javascript"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #7F848E;font-style: italic;">// Estimate gas then add 20% buffer</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #C678DD;">const</span><span style="color: #E5C07B;"> gasEstimate</span><span style="color: #56B6C2;"> =</span><span style="color: #C678DD;"> await</span><span style="color: #E5C07B;"> contract</span><span>.</span><span style="color: #E5C07B;">riskyOperation</span><span>.</span><span style="color: #61AFEF;">estimateGas</span><span>(</span><span style="color: #D19A66;">100</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span><span style="color: #C678DD;">const</span><span style="color: #E5C07B;"> safeLimit</span><span style="color: #56B6C2;"> =</span><span style="color: #E5C07B;"> Math</span><span>.</span><span style="color: #61AFEF;">floor</span><span>(</span><span style="color: #E06C75;">gasEstimate</span><span style="color: #56B6C2;"> *</span><span style="color: #D19A66;"> 1.2</span><span>);</span></span></code></pre> <p>A 10-20% buffer is standard practice. For functions with variable loop counts, test with realistic inputs before deploying.</p> <h3 id="avoiding-unbounded-loops">Avoiding Unbounded Loops</h3> <p>The most common cause of out-of-gas failures is iterating over an array whose size can grow without bound.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="bad-pattern.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> BadPattern</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #E5C07B;"> address</span><span>[]</span><span style="color: #C678DD;"> public</span><span> users;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #7F848E;font-style: italic;"> // DANGEROUS: gas cost is unknown and grows over time</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> processAll</span><span>()</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #C678DD;"> for</span><span> (</span><span style="color: #E5C07B;">uint</span><span> i </span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> 0</span><span>; i &lt; users.length; i</span><span style="color: #56B6C2;">++</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #7F848E;font-style: italic;"> // process each user</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span>}</span></span></code></pre><pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="good-pattern.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> GoodPattern</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #E5C07B;"> address</span><span>[]</span><span style="color: #C678DD;"> public</span><span> users;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #7F848E;font-style: italic;"> // SAFE: caller controls the batch size</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> processBatch</span><span>(</span><span style="color: #E5C07B;">uint</span><span style="color: #E06C75;font-style: italic;"> start</span><span>,</span><span style="color: #E5C07B;"> uint</span><span style="color: #E06C75;font-style: italic;"> end</span><span>)</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #C678DD;"> require</span><span>(end &lt;</span><span style="color: #56B6C2;">=</span><span> users.length,</span><span style="color: #98C379;"> &quot;Out of bounds&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #C678DD;"> require</span><span>(end </span><span style="color: #56B6C2;">-</span><span> start &lt;</span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> 100</span><span>,</span><span style="color: #98C379;"> &quot;Batch too large&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #C678DD;"> for</span><span> (</span><span style="color: #E5C07B;">uint</span><span> i </span><span style="color: #56B6C2;">=</span><span> start; i &lt; end; i</span><span style="color: #56B6C2;">++</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #7F848E;font-style: italic;"> // process user</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span>}</span></span></code></pre> <p>The batch pattern lets you process large arrays across multiple transactions without hitting the block gas limit.</p> <h3 id="checking-remaining-gas-at-runtime">Checking Remaining Gas at Runtime</h3> <p>For complex operations, you can read remaining gas mid-execution and bail out early if you are running low:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> GasAware</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> complexOperation</span><span>()</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #C678DD;"> require</span><span>(</span><span style="color: #E5C07B;">gasleft</span><span>() &gt;</span><span style="color: #D19A66;"> 100000</span><span>,</span><span style="color: #98C379;"> &quot;Not enough gas provided&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #7F848E;font-style: italic;"> // perform expensive work</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #C678DD;"> if</span><span> (</span><span style="color: #E5C07B;">gasleft</span><span>() &lt;</span><span style="color: #D19A66;"> 50000</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #C678DD;"> revert</span><span>(</span><span style="color: #98C379;">&quot;Insufficient gas to complete safely&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span>}</span></span></code></pre> <p>Use <code>gasleft()</code> sparingly. It is useful for guard rails in loops or multi-step operations, but it adds complexity.</p> <h2 id="variable-packing-for-storage-optimization">Variable Packing for Storage Optimization</h2> <p>Storage is the most expensive part of a Solidity contract. Variable packing is a technique that reduces the number of storage slots your contract uses, which directly reduces gas costs.</p> <h3 id="how-evm-storage-works">How EVM Storage Works</h3> <p>The EVM stores state variables in 32-byte (256-bit) slots. Reading or writing a slot costs the same amount of gas whether you use 1 byte or all 32 bytes. If you declare your variables carelessly, you can waste entire slots on variables that only need a few bytes.</p> <p>Consider this unpacked layout:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="bad-packing.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> UnpackedStorage</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #E5C07B;"> uint8</span><span> a;</span><span style="color: #7F848E;font-style: italic;"> // Slot 0: uses 1 byte, 31 bytes wasted</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #E5C07B;"> uint256</span><span> b;</span><span style="color: #7F848E;font-style: italic;"> // Slot 1: full 32 bytes</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #E5C07B;"> uint8</span><span> c;</span><span style="color: #7F848E;font-style: italic;"> // Slot 2: uses 1 byte, 31 bytes wasted</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #E5C07B;"> uint256</span><span> d;</span><span style="color: #7F848E;font-style: italic;"> // Slot 3: full 32 bytes</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #E5C07B;"> uint8</span><span> e;</span><span style="color: #7F848E;font-style: italic;"> // Slot 4: uses 1 byte, 31 bytes wasted</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #7F848E;font-style: italic;">// 5 storage slots = 5 x 20000 = 100000 gas to initialize</span></span></code></pre> <p>Now the same data, packed:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="good-packing.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> PackedStorage</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #E5C07B;"> uint8</span><span> a;</span><span style="color: #7F848E;font-style: italic;"> // Slot 0, byte 0</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #E5C07B;"> uint8</span><span> c;</span><span style="color: #7F848E;font-style: italic;"> // Slot 0, byte 1</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #E5C07B;"> uint8</span><span> e;</span><span style="color: #7F848E;font-style: italic;"> // Slot 0, byte 2</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #E5C07B;"> uint256</span><span> b;</span><span style="color: #7F848E;font-style: italic;"> // Slot 1: full 32 bytes</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #E5C07B;"> uint256</span><span> d;</span><span style="color: #7F848E;font-style: italic;"> // Slot 2: full 32 bytes</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #7F848E;font-style: italic;">// 3 storage slots = 3 x 20000 = 60000 gas to initialize</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #7F848E;font-style: italic;">// Saves 40000 gas (40% reduction)</span></span></code></pre> <p>The EVM packs variables into the same slot automatically, but only if they are declared sequentially and fit together. Declaration order matters.</p> <h3 id="common-variable-sizes">Common Variable Sizes</h3> <table><thead><tr><th>Type</th><th>Size</th></tr></thead><tbody> <tr><td><code>bool</code></td><td>1 byte</td></tr> <tr><td><code>uint8</code></td><td>1 byte</td></tr> <tr><td><code>uint16</code></td><td>2 bytes</td></tr> <tr><td><code>uint32</code></td><td>4 bytes</td></tr> <tr><td><code>uint64</code></td><td>8 bytes</td></tr> <tr><td><code>uint128</code></td><td>16 bytes</td></tr> <tr><td><code>uint256</code></td><td>32 bytes</td></tr> <tr><td><code>address</code></td><td>20 bytes</td></tr> <tr><td><code>bytes32</code></td><td>32 bytes</td></tr> </tbody></table> <h3 id="practical-examples">Practical Examples</h3> <p><strong>Token contract storage layout:</strong></p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="token-bad.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #7F848E;font-style: italic;">// BAD: 4 storage slots = 80000 gas</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> TokenBad</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span><span style="color: #E5C07B;"> address</span><span> owner;</span><span style="color: #7F848E;font-style: italic;"> // Slot 0: 20 bytes + 12 bytes wasted</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">4</span><span style="color: #E5C07B;"> uint256</span><span> totalSupply;</span><span style="color: #7F848E;font-style: italic;"> // Slot 1: 32 bytes</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">5</span><span style="color: #E5C07B;"> bool</span><span> paused;</span><span style="color: #7F848E;font-style: italic;"> // Slot 2: 1 byte + 31 bytes wasted</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">6</span><span style="color: #E5C07B;"> uint256</span><span> lastUpdate;</span><span style="color: #7F848E;font-style: italic;"> // Slot 3: 32 bytes</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">7</span><span>}</span></span></code></pre><pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="token-good.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #7F848E;font-style: italic;">// GOOD: 3 storage slots = 60000 gas</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> TokenGood</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #E5C07B;"> address</span><span> owner;</span><span style="color: #7F848E;font-style: italic;"> // Slot 0: 20 bytes</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #E5C07B;"> bool</span><span> paused;</span><span style="color: #7F848E;font-style: italic;"> // Slot 0: 1 byte (packed with owner)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #E5C07B;"> uint256</span><span> totalSupply;</span><span style="color: #7F848E;font-style: italic;"> // Slot 1: 32 bytes</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #E5C07B;"> uint256</span><span> lastUpdate;</span><span style="color: #7F848E;font-style: italic;"> // Slot 2: 32 bytes</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #7F848E;font-style: italic;">// Saves 20000 gas per deployment</span></span></code></pre> <p><strong>User profile with many small fields:</strong></p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="user-profile.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #7F848E;font-style: italic;">// BAD: 7 slots = 140000 gas</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> UserProfileBad</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #E5C07B;"> uint256</span><span> userId;</span><span style="color: #7F848E;font-style: italic;"> // Slot 0</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #E5C07B;"> uint8</span><span> age;</span><span style="color: #7F848E;font-style: italic;"> // Slot 1</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #E5C07B;"> bool</span><span> isActive;</span><span style="color: #7F848E;font-style: italic;"> // Slot 2</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #E5C07B;"> uint16</span><span> reputation;</span><span style="color: #7F848E;font-style: italic;"> // Slot 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #E5C07B;"> address</span><span> wallet;</span><span style="color: #7F848E;font-style: italic;"> // Slot 4</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #E5C07B;"> uint32</span><span> joinDate;</span><span style="color: #7F848E;font-style: italic;"> // Slot 5</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #E5C07B;"> bool</span><span> isPremium;</span><span style="color: #7F848E;font-style: italic;"> // Slot 6</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span style="color: #7F848E;font-style: italic;">// GOOD: 3 slots = 60000 gas</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> UserProfileGood</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span style="color: #E5C07B;"> uint256</span><span> userId;</span><span style="color: #7F848E;font-style: italic;"> // Slot 0: 32 bytes</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span style="color: #7F848E;font-style: italic;"> // Slot 1: 20 + 4 + 2 + 1 + 1 + 1 = 29 bytes (fits in 32)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">17</span><span style="color: #E5C07B;"> address</span><span> wallet;</span><span style="color: #7F848E;font-style: italic;"> // Slot 1: 20 bytes</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">18</span><span style="color: #E5C07B;"> uint32</span><span> joinDate;</span><span style="color: #7F848E;font-style: italic;"> // Slot 1: 4 bytes</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">19</span><span style="color: #E5C07B;"> uint16</span><span> reputation;</span><span style="color: #7F848E;font-style: italic;"> // Slot 1: 2 bytes</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">20</span><span style="color: #E5C07B;"> uint8</span><span> age;</span><span style="color: #7F848E;font-style: italic;"> // Slot 1: 1 byte</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">21</span><span style="color: #E5C07B;"> bool</span><span> isActive;</span><span style="color: #7F848E;font-style: italic;"> // Slot 1: 1 byte</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">22</span><span style="color: #E5C07B;"> bool</span><span> isPremium;</span><span style="color: #7F848E;font-style: italic;"> // Slot 1: 1 byte</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">23</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">24</span><span style="color: #7F848E;font-style: italic;">// Saves 80000 gas per user (57% reduction)</span></span></code></pre><h3 id="packing-rules-for-structs-and-mappings">Packing Rules for Structs and Mappings</h3> <p>Structs follow the same packing rules as contract-level variables:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">struct</span><span style="color: #E5C07B;"> BadStruct</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #E5C07B;"> uint8</span><span> a;</span><span style="color: #7F848E;font-style: italic;"> // Slot 0</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #E5C07B;"> uint256</span><span> b;</span><span style="color: #7F848E;font-style: italic;"> // Slot 1 (breaks packing)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #E5C07B;"> uint8</span><span> c;</span><span style="color: #7F848E;font-style: italic;"> // Slot 2</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #C678DD;">struct</span><span style="color: #E5C07B;"> GoodStruct</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #E5C07B;"> uint8</span><span> a;</span><span style="color: #7F848E;font-style: italic;"> // Slot 0</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #E5C07B;"> uint8</span><span> c;</span><span style="color: #7F848E;font-style: italic;"> // Slot 0 (packed)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #E5C07B;"> uint256</span><span> b;</span><span style="color: #7F848E;font-style: italic;"> // Slot 1</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span>}</span></span></code></pre> <p>Mappings and dynamic arrays always start a new storage slot and cannot be packed with adjacent variables:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> MappingLayout</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #E5C07B;"> uint128</span><span> a;</span><span style="color: #7F848E;font-style: italic;"> // Slot 0, first 16 bytes</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span><span style="color: #E5C07B;"> uint128</span><span> b;</span><span style="color: #7F848E;font-style: italic;"> // Slot 0, last 16 bytes</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">4</span><span style="color: #C678DD;"> mapping</span><span>(</span><span style="color: #E5C07B;">address</span><span> =&gt;</span><span style="color: #E5C07B;"> uint</span><span>) c;</span><span style="color: #7F848E;font-style: italic;"> // Slot 1 (always starts new slot)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">5</span><span style="color: #E5C07B;"> uint128</span><span> d;</span><span style="color: #7F848E;font-style: italic;"> // Slot 2 (cannot pack with mapping)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">6</span><span>}</span></span></code></pre><h3 id="real-world-example-nft-struct">Real-World Example: NFT Struct</h3> <p>Here is how packing applies to a token struct in an NFT contract:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="nft-before.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #7F848E;font-style: italic;">// BEFORE: 8 slots per token = 160000 gas</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;">struct</span><span style="color: #E5C07B;"> Token</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #E5C07B;"> uint256</span><span> tokenId;</span><span style="color: #7F848E;font-style: italic;"> // Slot 0</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #E5C07B;"> address</span><span> owner;</span><span style="color: #7F848E;font-style: italic;"> // Slot 1</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #E5C07B;"> address</span><span> approved;</span><span style="color: #7F848E;font-style: italic;"> // Slot 2</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #E5C07B;"> uint256</span><span> price;</span><span style="color: #7F848E;font-style: italic;"> // Slot 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #E5C07B;"> bool</span><span> isListed;</span><span style="color: #7F848E;font-style: italic;"> // Slot 4</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #E5C07B;"> uint8</span><span> rarity;</span><span style="color: #7F848E;font-style: italic;"> // Slot 5</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #E5C07B;"> uint32</span><span> mintedAt;</span><span style="color: #7F848E;font-style: italic;"> // Slot 6</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #E5C07B;"> uint16</span><span> generation;</span><span style="color: #7F848E;font-style: italic;"> // Slot 7</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span>}</span></span></code></pre><pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="nft-after.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #7F848E;font-style: italic;">// AFTER: 4 slots per token = 80000 gas</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;">struct</span><span style="color: #E5C07B;"> Token</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #E5C07B;"> uint256</span><span> tokenId;</span><span style="color: #7F848E;font-style: italic;"> // Slot 0: 32 bytes</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #E5C07B;"> uint256</span><span> price;</span><span style="color: #7F848E;font-style: italic;"> // Slot 1: 32 bytes</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #7F848E;font-style: italic;"> // Slot 2: 20 + 4 + 2 + 1 + 1 = 28 bytes</span></span> <span class="giallo-l" style="background-color: #2C313C;"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #E5C07B;"> address</span><span> owner;</span><span style="color: #7F848E;font-style: italic;"> // Slot 2: 20 bytes</span></span> <span class="giallo-l" style="background-color: #2C313C;"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #E5C07B;"> uint32</span><span> mintedAt;</span><span style="color: #7F848E;font-style: italic;"> // Slot 2: 4 bytes</span></span> <span class="giallo-l" style="background-color: #2C313C;"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #E5C07B;"> uint16</span><span> generation;</span><span style="color: #7F848E;font-style: italic;"> // Slot 2: 2 bytes</span></span> <span class="giallo-l" style="background-color: #2C313C;"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #E5C07B;"> uint8</span><span> rarity;</span><span style="color: #7F848E;font-style: italic;"> // Slot 2: 1 byte</span></span> <span class="giallo-l" style="background-color: #2C313C;"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span style="color: #E5C07B;"> bool</span><span> isListed;</span><span style="color: #7F848E;font-style: italic;"> // Slot 2: 1 byte</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span style="color: #E5C07B;"> address</span><span> approved;</span><span style="color: #7F848E;font-style: italic;"> // Slot 3: 20 bytes</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span>}</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span style="color: #7F848E;font-style: italic;">// Saves 80000 gas per token (50% reduction)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span style="color: #7F848E;font-style: italic;">// For 10000 NFTs: 800 million gas saved in total</span></span></code></pre><h3 id="the-tradeoff-packing-adds-computation">The Tradeoff: Packing Adds Computation</h3> <p>Packing is not free. When you read or write a packed variable, the EVM has to read the full 32-byte slot, extract your variable with bitwise operations, modify it, and write the slot back. This adds a small computation cost.</p> <p>In practice, packing is almost always worth it because storage operations are so much more expensive than arithmetic. Here is a concrete comparison:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="packed.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> PackedUpdate</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #E5C07B;"> uint128</span><span> a;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #E5C07B;"> uint128</span><span> b;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> updateBoth</span><span>(</span><span style="color: #E5C07B;">uint128</span><span style="color: #E06C75;font-style: italic;"> newA</span><span>,</span><span style="color: #E5C07B;"> uint128</span><span style="color: #E06C75;font-style: italic;"> newB</span><span>)</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span> a </span><span style="color: #56B6C2;">=</span><span> newA;</span><span style="color: #7F848E;font-style: italic;"> // First write to slot 0: 20000 gas</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span> b </span><span style="color: #56B6C2;">=</span><span> newB;</span><span style="color: #7F848E;font-style: italic;"> // Second write to same slot (warm): 5000 gas</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #7F848E;font-style: italic;"> // Total: 25000 gas</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span>}</span></span></code></pre><pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="unpacked.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> UnpackedUpdate</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #E5C07B;"> uint256</span><span> a;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #E5C07B;"> uint256</span><span> b;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> updateBoth</span><span>(</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> newA</span><span>,</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> newB</span><span>)</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span> a </span><span style="color: #56B6C2;">=</span><span> newA;</span><span style="color: #7F848E;font-style: italic;"> // Write to slot 0: 20000 gas</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span> b </span><span style="color: #56B6C2;">=</span><span> newB;</span><span style="color: #7F848E;font-style: italic;"> // Write to slot 1: 20000 gas</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #7F848E;font-style: italic;"> // Total: 40000 gas</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span>}</span></span></code></pre> <p>The packed version saves 15000 gas even accounting for the extra computation. The exception is when two packed variables are always read or written independently and rarely together. In that case, packing may add overhead without benefit. Measure before assuming.</p> <h2 id="other-optimization-techniques">Other Optimization Techniques</h2> <h3 id="cache-storage-reads-in-memory">Cache Storage Reads in Memory</h3> <p>Every time you read a storage variable, it costs 2100 gas (cold) or 100 gas (warm). If you read the same variable multiple times in a function, cache it in a local memory variable first.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> transfer</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> to</span><span>,</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>)</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #7F848E;font-style: italic;"> // Cache the balance once instead of reading storage twice</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #E5C07B;"> uint256</span><span> senderBalance </span><span style="color: #56B6C2;">=</span><span> balances[</span><span style="color: #E5C07B;">msg.sender</span><span>];</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;"> require</span><span>(senderBalance &gt;</span><span style="color: #56B6C2;">=</span><span> amount,</span><span style="color: #98C379;"> &quot;Insufficient balance&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span> balances[</span><span style="color: #E5C07B;">msg.sender</span><span>]</span><span style="color: #56B6C2;"> =</span><span> senderBalance </span><span style="color: #56B6C2;">-</span><span> amount;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span> balances[to]</span><span style="color: #56B6C2;"> +=</span><span> amount;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span>}</span></span></code></pre><h3 id="use-events-for-data-you-do-not-need-on-chain">Use Events for Data You Do Not Need On-Chain</h3> <p>If you need to record something for off-chain use but never read it inside the contract, use events. They cost roughly 375 gas per indexed topic, far cheaper than a storage write.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #C678DD;">event</span><span style="color: #E5C07B;"> Transfer</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #C678DD;"> indexed</span><span style="color: #E06C75;font-style: italic;"> from</span><span>, </span><span style="color: #E5C07B;">address</span><span style="color: #C678DD;"> indexed</span><span style="color: #E06C75;font-style: italic;"> to</span><span>, </span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> transfer</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> to</span><span>,</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>)</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">4</span><span style="color: #7F848E;font-style: italic;"> // state changes here</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">5</span><span style="color: #C678DD;"> emit</span><span style="color: #61AFEF;"> Transfer</span><span>(</span><span style="color: #E5C07B;">msg.sender</span><span>, to, amount);</span><span style="color: #7F848E;font-style: italic;"> // ~1500 gas total</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">6</span><span>}</span></span></code></pre><h3 id="storage-refunds">Storage Refunds</h3> <p>Setting a storage slot to zero gives you a gas refund of 15000 gas. This makes cleanup functions cheaper to run.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> close</span><span>()</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #C678DD;"> delete</span><span> balances[</span><span style="color: #E5C07B;">msg.sender</span><span>];</span><span style="color: #7F848E;font-style: italic;"> // Refunds 15000 gas</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span><span>}</span></span></code></pre> <p>Refunds are capped at 20% of total gas used for the transaction, so you cannot refund more than you spent.</p> <h2 id="putting-it-together-an-optimized-token-contract">Putting It Together: An Optimized Token Contract</h2> <p>This example combines the techniques covered above into a working token contract:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="optimized-token.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> OptimizedToken</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #7F848E;font-style: italic;"> // Dynamic strings take their own slots</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #E5C07B;"> string</span><span style="color: #C678DD;"> public</span><span> name;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #E5C07B;"> string</span><span style="color: #C678DD;"> public</span><span> symbol;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #E5C07B;"> uint256</span><span style="color: #C678DD;"> public</span><span> totalSupply;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #7F848E;font-style: italic;"> // Slot: 20 + 1 + 1 = 22 bytes, packed together</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #E5C07B;"> address</span><span style="color: #C678DD;"> public</span><span> owner;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #E5C07B;"> bool</span><span style="color: #C678DD;"> public</span><span> paused;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span style="color: #E5C07B;"> uint8</span><span style="color: #C678DD;"> public</span><span> decimals;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span style="color: #C678DD;"> mapping</span><span>(</span><span style="color: #E5C07B;">address</span><span> =&gt;</span><span style="color: #E5C07B;"> uint256</span><span>)</span><span style="color: #C678DD;"> private</span><span> balances;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span style="color: #C678DD;"> event</span><span style="color: #E5C07B;"> Transfer</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #C678DD;"> indexed</span><span style="color: #E06C75;font-style: italic;"> from</span><span>, </span><span style="color: #E5C07B;">address</span><span style="color: #C678DD;"> indexed</span><span style="color: #E06C75;font-style: italic;"> to</span><span>, </span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">17</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> transfer</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> to</span><span>,</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>)</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">18</span><span style="color: #C678DD;"> require</span><span>(!paused,</span><span style="color: #98C379;"> &quot;Contract is paused&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">19</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">20</span><span style="color: #7F848E;font-style: italic;"> // Read storage once, use local variable for checks</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">21</span><span style="color: #E5C07B;"> uint256</span><span> senderBalance </span><span style="color: #56B6C2;">=</span><span> balances[</span><span style="color: #E5C07B;">msg.sender</span><span>];</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">22</span><span style="color: #C678DD;"> require</span><span>(senderBalance &gt;</span><span style="color: #56B6C2;">=</span><span> amount,</span><span style="color: #98C379;"> &quot;Insufficient balance&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">23</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">24</span><span> balances[</span><span style="color: #E5C07B;">msg.sender</span><span>]</span><span style="color: #56B6C2;"> =</span><span> senderBalance </span><span style="color: #56B6C2;">-</span><span> amount;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">25</span><span> balances[to]</span><span style="color: #56B6C2;"> +=</span><span> amount;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">26</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">27</span><span style="color: #C678DD;"> emit</span><span style="color: #61AFEF;"> Transfer</span><span>(</span><span style="color: #E5C07B;">msg.sender</span><span>, to, amount);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">28</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">29</span><span>}</span></span></code></pre> <p>The contract packs <code>owner</code>, <code>paused</code>, and <code>decimals</code> into one slot, caches the sender balance to avoid a redundant storage read, and uses an event for the transfer log instead of extra storage.</p> <h2 id="summary">Summary</h2> <p>Gas optimization is not premature optimization. In Ethereum, every byte you waste costs your users real money. The two techniques covered here give you the most leverage:</p> <p><strong>Gas limits</strong> protect you from runaway transactions. Always add a 10-20% buffer on top of estimated gas. Never write unbounded loops. Use batching when you need to process large arrays.</p> <p><strong>Variable packing</strong> cuts storage costs by filling each 32-byte slot fully. Declare small types together, group related fields in structs, and remember that mappings always start a new slot. For a large NFT collection or a frequently-updated contract, the savings compound quickly.</p> <p>Start with packing your storage layout before deployment. It costs nothing at that stage and the savings are permanent.</p> 2025-11-01T00:00:00+00:00 2025-11-01T00:00:00+00:00 Akash Vaghela https://akash11.com/blog/view-and-pure-functions-in-solidity/ <p>Solidity gives you two function modifiers, <code>view</code> and <code>pure</code>, that let you declare upfront whether a function reads or modifies blockchain state. The compiler enforces these declarations, which means bugs get caught early and other developers can understand your code at a glance.</p> <p>This post explains what each modifier does, what counts as reading or modifying state, and when to use each one.</p> <h2 id="what-state-means-in-a-smart-contract">What "State" Means in a Smart Contract</h2> <p>State is any data stored permanently on the blockchain. This includes:</p> <ul> <li>Storage variables declared at the contract level</li> <li>Account balances (including <code>address(this).balance</code>)</li> <li>Data in other contracts</li> <li>Block and transaction context (<code>block.timestamp</code>, <code>msg.sender</code>, etc.)</li> </ul> <p>Reading or writing state costs gas. Functions that interact with state need to be part of a transaction, and transactions cost gas. Functions that do not touch state can sometimes be executed off-chain for free.</p> <h2 id="view-functions">View Functions</h2> <p>A <code>view</code> function promises it will read state but never modify it. The compiler enforces this. If your function tries to write to a storage variable or emit an event, it will not compile as <code>view</code>.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="Counter.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Counter</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #E5C07B;"> uint256</span><span style="color: #C678DD;"> public</span><span> count </span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> 0</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #7F848E;font-style: italic;"> // Reads state, returns it unchanged</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> getCount</span><span>()</span><span style="color: #C678DD;"> public view returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #C678DD;"> return</span><span> count;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #7F848E;font-style: italic;"> // Reads state and does a calculation</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> getDoubleCount</span><span>()</span><span style="color: #C678DD;"> public view returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span style="color: #C678DD;"> return</span><span> count </span><span style="color: #56B6C2;">*</span><span style="color: #D19A66;"> 2</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span>}</span></span></code></pre> <p>When you call a <code>view</code> function directly from outside the blockchain (using <code>eth_call</code>), it costs no gas. The node executes it locally and returns the result. However, if a regular state-changing function calls a <code>view</code> function internally during a transaction, that internal call still consumes gas as part of the overall transaction cost.</p> <h2 id="pure-functions">Pure Functions</h2> <p>A <code>pure</code> function is more restricted than <code>view</code>. It cannot read state and cannot modify state. It only works with its input parameters.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="MathHelper.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> MathHelper</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #7F848E;font-style: italic;"> // No state read, no state write</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> add</span><span>(</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> a</span><span>,</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> b</span><span>)</span><span style="color: #C678DD;"> public pure returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;"> return</span><span> a </span><span style="color: #56B6C2;">+</span><span> b;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> multiply</span><span>(</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> x</span><span>,</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> y</span><span>)</span><span style="color: #C678DD;"> public pure returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #C678DD;"> return</span><span> x </span><span style="color: #56B6C2;">*</span><span> y;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span>}</span></span></code></pre> <p><code>pure</code> functions are useful for utility logic: hashing, encoding, arithmetic, or any computation that does not depend on contract data. Because they have no side effects and no dependencies on storage, they behave like mathematical functions. Same input always produces same output.</p> <h2 id="what-breaks-each-promise">What Breaks Each Promise</h2> <p>These actions will cause the compiler to reject a <code>view</code> or <code>pure</code> declaration.</p> <p><strong>Breaks <code>view</code> (modifies state):</strong></p> <ul> <li>Writing to a storage variable</li> <li>Emitting an event</li> <li>Creating another contract</li> <li>Using <code>selfdestruct</code></li> <li>Sending Ether</li> <li>Calling a function that is not <code>view</code> or <code>pure</code></li> <li>Using low-level calls (<code>call</code>, <code>delegatecall</code>, etc.)</li> <li>Writing state via inline assembly</li> </ul> <p><strong>Breaks <code>pure</code> (reads state):</strong></p> <ul> <li>Reading a storage variable</li> <li>Accessing <code>address(this).balance</code> or any other address balance</li> <li>Accessing <code>block</code>, <code>tx</code>, or <code>msg</code> properties (except <code>msg.sig</code> and <code>msg.data</code>)</li> <li>Calling a function that is not <code>pure</code></li> <li>Reading state via inline assembly</li> </ul> <blockquote class="markdown-alert-note"> <p><code>msg.sig</code> and <code>msg.data</code> are allowed inside <code>pure</code> functions. They describe the call itself, not the blockchain state.</p> </blockquote> <h2 id="all-three-types-together">All Three Types Together</h2> <p>Here is a single contract showing a state-modifying function, a <code>view</code> function, and a <code>pure</code> function side by side:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="Example.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Example</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #E5C07B;"> uint256</span><span style="color: #C678DD;"> public</span><span> storedNumber </span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> 42</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #7F848E;font-style: italic;"> // Regular function: modifies state</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> setNumber</span><span>(</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> newNumber</span><span>)</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span> storedNumber </span><span style="color: #56B6C2;">=</span><span> newNumber;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #7F848E;font-style: italic;"> // View function: reads state, no modification</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> getNumber</span><span>()</span><span style="color: #C678DD;"> public view returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span style="color: #C678DD;"> return</span><span> storedNumber;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span style="color: #7F848E;font-style: italic;"> // View function: reads state and transforms it</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> getNumberPlusTen</span><span>()</span><span style="color: #C678DD;"> public view returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span style="color: #C678DD;"> return</span><span> storedNumber </span><span style="color: #56B6C2;">+</span><span style="color: #D19A66;"> 10</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">17</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">18</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">19</span><span style="color: #7F848E;font-style: italic;"> // Pure function: no state involved</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">20</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> add</span><span>(</span><span style="color: #E5C07B;">uint256</span><span style="color: #E06C75;font-style: italic;"> a</span><span>,</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> b</span><span>)</span><span style="color: #C678DD;"> public pure returns</span><span> (</span><span style="color: #E5C07B;">uint256</span><span>) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">21</span><span style="color: #C678DD;"> return</span><span> a </span><span style="color: #56B6C2;">+</span><span> b;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">22</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">23</span><span>}</span></span></code></pre><h2 id="why-this-matters">Why This Matters</h2> <p><strong>Gas savings.</strong> External calls to <code>view</code> and <code>pure</code> functions execute off-chain for free when called directly. If your frontend or another service only needs to read data, declaring the function as <code>view</code> lets callers skip the transaction entirely.</p> <p><strong>Compiler enforcement.</strong> The compiler will reject a <code>view</code> function that tries to write state, and reject a <code>pure</code> function that tries to read it. This catches an entire class of accidental side effects before deployment.</p> <p><strong>Readability.</strong> A developer reading your code does not need to trace through the function body to understand whether it modifies anything. The keyword says it upfront.</p> <h2 id="when-to-use-each">When to Use Each</h2> <p>Use a regular function when you need to write to storage, emit events, or change contract state in any way.</p> <p>Use <code>view</code> when you need to read storage variables, balances, or block context without changing anything.</p> <p>Use <code>pure</code> when your function only needs its input parameters, nothing from storage or the environment.</p> <p>If you are unsure which to use, start with <code>pure</code>. If the compiler rejects it because you are reading state, upgrade to <code>view</code>. If the compiler rejects that because you are writing state, remove the modifier entirely.</p> 2025-10-20T00:00:00+00:00 2025-10-20T00:00:00+00:00 Akash Vaghela https://akash11.com/blog/solidity-custom-errors-gas-savings/ <p>Solidity 0.8.4 introduced custom errors. They are a direct replacement for <code>require</code> statements with string messages. The benefit is straightforward: lower gas costs, both at deployment and at runtime.</p> <p>This post explains how custom errors work, how much gas they save and why, and how to migrate existing contracts to use them.</p> <h2 id="the-problem-with-string-errors">The Problem with String Errors</h2> <p>The traditional pattern for error handling in Solidity looks like this:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> OldWayErrors</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #E5C07B;"> address</span><span style="color: #C678DD;"> public</span><span> owner;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;"> constructor</span><span>() {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span> owner </span><span style="color: #56B6C2;">=</span><span style="color: #E5C07B;"> msg.sender</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> restrictedFunction</span><span>()</span><span style="color: #C678DD;"> public view</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #C678DD;"> require</span><span>(</span><span style="color: #E5C07B;">msg.sender</span><span> == owner,</span><span style="color: #98C379;"> &quot;Only owner can call this function&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span>}</span></span></code></pre> <p>Every string you pass to <code>require</code> gets embedded in the contract bytecode. The longer the string, the more bytes are stored on-chain. This affects deployment cost directly. Multiply that across a contract with 10 or 20 functions, each with one or more require checks, and the bytecode bloat becomes significant.</p> <p>At runtime, reverting with a string message means the EVM must ABI-encode that string and return it as revert data. That encoding costs gas on every failed transaction.</p> <h2 id="how-custom-errors-work">How Custom Errors Work</h2> <p>A custom error is declared at the contract level using the <code>error</code> keyword. When a condition fails, you use <code>revert</code> with that error instead of <code>require</code>.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> NewWayErrors</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #E5C07B;"> address</span><span style="color: #C678DD;"> public</span><span> owner;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;"> error</span><span style="color: #E5C07B;"> Unauthorized</span><span>();</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #C678DD;"> constructor</span><span>() {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span> owner </span><span style="color: #56B6C2;">=</span><span style="color: #E5C07B;"> msg.sender</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> restrictedFunction</span><span>()</span><span style="color: #C678DD;"> public view</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span style="color: #C678DD;"> if</span><span> (</span><span style="color: #E5C07B;">msg.sender</span><span> != owner) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span style="color: #C678DD;"> revert</span><span style="color: #61AFEF;"> Unauthorized</span><span>();</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span>}</span></span></code></pre> <p>Under the hood, Solidity hashes the error signature (for example, <code>Unauthorized()</code>) and takes the first 4 bytes. This is the same mechanism used for function selectors. When the transaction reverts, those 4 bytes are returned as the revert data instead of an encoded string.</p> <p>4 bytes versus dozens or hundreds of bytes per error. That is where the savings come from.</p> <h2 id="gas-savings-deployment">Gas Savings: Deployment</h2> <p>Consider a contract with several common validation checks:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="TraditionalErrors.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> TraditionalErrors</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;"> mapping</span><span>(</span><span style="color: #E5C07B;">address</span><span> =&gt;</span><span style="color: #E5C07B;"> uint256</span><span>)</span><span style="color: #C678DD;"> public</span><span> balances;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> transfer</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> to</span><span>,</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>)</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #C678DD;"> require</span><span>(to !=</span><span style="color: #E5C07B;"> address</span><span>(</span><span style="color: #D19A66;">0</span><span>),</span><span style="color: #98C379;"> &quot;Cannot transfer to zero address&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #C678DD;"> require</span><span>(balances[</span><span style="color: #E5C07B;">msg.sender</span><span>] &gt;</span><span style="color: #56B6C2;">=</span><span> amount,</span><span style="color: #98C379;"> &quot;Insufficient balance&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #C678DD;"> require</span><span>(amount &gt;</span><span style="color: #D19A66;"> 0</span><span>,</span><span style="color: #98C379;"> &quot;Amount must be greater than zero&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span> balances[</span><span style="color: #E5C07B;">msg.sender</span><span>]</span><span style="color: #56B6C2;"> -=</span><span> amount;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span> balances[to]</span><span style="color: #56B6C2;"> +=</span><span> amount;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span>}</span></span></code></pre> <p>Those three strings total around 80 characters. Each character is one byte in the bytecode. In a real contract with many functions, this adds up fast.</p> <p>Now the same logic with custom errors:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="ModernErrors.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> ModernErrors</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;"> mapping</span><span>(</span><span style="color: #E5C07B;">address</span><span> =&gt;</span><span style="color: #E5C07B;"> uint256</span><span>)</span><span style="color: #C678DD;"> public</span><span> balances;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;"> error</span><span style="color: #E5C07B;"> ZeroAddress</span><span>();</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #C678DD;"> error</span><span style="color: #E5C07B;"> InsufficientBalance</span><span>();</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #C678DD;"> error</span><span style="color: #E5C07B;"> InvalidAmount</span><span>();</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> transfer</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> to</span><span>,</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>)</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #C678DD;"> if</span><span> (to ==</span><span style="color: #E5C07B;"> address</span><span>(</span><span style="color: #D19A66;">0</span><span>))</span><span style="color: #C678DD;"> revert</span><span style="color: #61AFEF;"> ZeroAddress</span><span>();</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #C678DD;"> if</span><span> (balances[</span><span style="color: #E5C07B;">msg.sender</span><span>] &lt; amount)</span><span style="color: #C678DD;"> revert</span><span style="color: #61AFEF;"> InsufficientBalance</span><span>();</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span style="color: #C678DD;"> if</span><span> (amount ==</span><span style="color: #D19A66;"> 0</span><span>)</span><span style="color: #C678DD;"> revert</span><span style="color: #61AFEF;"> InvalidAmount</span><span>();</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span> balances[</span><span style="color: #E5C07B;">msg.sender</span><span>]</span><span style="color: #56B6C2;"> -=</span><span> amount;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span> balances[to]</span><span style="color: #56B6C2;"> +=</span><span> amount;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span>}</span></span></code></pre> <p>Each error declaration contributes only a 4-byte selector to the bytecode. You can also reuse the same error in multiple functions without duplicating anything. Across a full contract, the deployment cost reduction typically falls between 5,000 and 15,000 gas depending on how many string messages you had and how long they were.</p> <h2 id="gas-savings-runtime">Gas Savings: Runtime</h2> <p>When a transaction reverts, the EVM returns revert data to the caller. With a string message, that data includes the full ABI-encoded string. With a custom error, it is just the 4-byte selector.</p> <p>The runtime saving per revert is smaller than the deployment saving, typically 20 to 50 gas. But for a protocol processing a high volume of transactions where a percentage of them revert (failed transfers, access control checks, slippage limits), that saving compounds across every failed call over the contract's lifetime.</p> <h2 id="adding-parameters-to-custom-errors">Adding Parameters to Custom Errors</h2> <p>Custom errors support parameters. This lets you include useful context in a revert without the overhead of string formatting.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> AdvancedErrors</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;"> mapping</span><span>(</span><span style="color: #E5C07B;">address</span><span> =&gt;</span><span style="color: #E5C07B;"> uint256</span><span>)</span><span style="color: #C678DD;"> public</span><span> balances;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;"> error</span><span style="color: #E5C07B;"> InsufficientBalance</span><span>(</span><span style="color: #E5C07B;">uint256</span><span> available,</span><span style="color: #E5C07B;"> uint256</span><span> required);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #C678DD;"> error</span><span style="color: #E5C07B;"> TransferFailed</span><span>(</span><span style="color: #E5C07B;">address</span><span> from,</span><span style="color: #E5C07B;"> address</span><span> to,</span><span style="color: #E5C07B;"> uint256</span><span> amount);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> transfer</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> to</span><span>,</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>)</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #E5C07B;"> uint256</span><span> balance </span><span style="color: #56B6C2;">=</span><span> balances[</span><span style="color: #E5C07B;">msg.sender</span><span>];</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #C678DD;"> if</span><span> (balance &lt; amount) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span style="color: #C678DD;"> revert</span><span style="color: #61AFEF;"> InsufficientBalance</span><span>(balance, amount);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span> balances[</span><span style="color: #E5C07B;">msg.sender</span><span>]</span><span style="color: #56B6C2;"> -=</span><span> amount;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span> balances[to]</span><span style="color: #56B6C2;"> +=</span><span> amount;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">17</span><span>}</span></span></code></pre> <p>The parameters are ABI-encoded and included in the revert data. The base cost is still lower than a string revert, because you avoid the fixed overhead of encoding a string type. And the error is more precise: a caller or interface can decode the exact values that caused the failure.</p> <blockquote class="markdown-alert-note"> <p>Adding parameters does increase the revert data size compared to a parameter-less custom error. The savings compared to an equivalent <code>require</code> with a formatted string are still present, but smaller. For the tightest gas optimisation, prefer parameter-less errors on hot paths.</p> </blockquote> <h2 id="organising-errors-in-a-real-contract">Organising Errors in a Real Contract</h2> <p>For contracts with many error cases, group errors by category at the top of the contract:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="TokenWithErrors.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> TokenWithErrors</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #7F848E;font-style: italic;"> // Access control</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #C678DD;"> error</span><span style="color: #E5C07B;"> Unauthorized</span><span>();</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;"> error</span><span style="color: #E5C07B;"> NotOwner</span><span>();</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #7F848E;font-style: italic;"> // Transfer validation</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #C678DD;"> error</span><span style="color: #E5C07B;"> ZeroAddress</span><span>();</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #C678DD;"> error</span><span style="color: #E5C07B;"> InsufficientBalance</span><span>(</span><span style="color: #E5C07B;">uint256</span><span> available,</span><span style="color: #E5C07B;"> uint256</span><span> required);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #C678DD;"> error</span><span style="color: #E5C07B;"> TransferToSelf</span><span>();</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span style="color: #7F848E;font-style: italic;"> // Contract state</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span style="color: #C678DD;"> error</span><span style="color: #E5C07B;"> ContractPaused</span><span>();</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span style="color: #C678DD;"> error</span><span style="color: #E5C07B;"> AlreadyInitialized</span><span>();</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span style="color: #7F848E;font-style: italic;"> // ... implementation</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span>}</span></span></code></pre> <p>This makes the error surface of a contract easy to read at a glance. Tools like Etherscan decode custom errors automatically, so users and developers still get meaningful information when a transaction fails. The 4-byte selector maps back to the human-readable error name in any ABI-aware tool.</p> <p>A function with multiple checks reads cleanly with the <code>if-revert</code> pattern:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> complexOperation</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> target</span><span>,</span><span style="color: #E5C07B;"> uint256</span><span style="color: #E06C75;font-style: italic;"> value</span><span>)</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;"> if</span><span> (target ==</span><span style="color: #E5C07B;"> address</span><span>(</span><span style="color: #D19A66;">0</span><span>))</span><span style="color: #C678DD;"> revert</span><span style="color: #61AFEF;"> ZeroAddress</span><span>();</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #C678DD;"> if</span><span> (</span><span style="color: #E5C07B;">msg.sender</span><span> != owner)</span><span style="color: #C678DD;"> revert</span><span style="color: #61AFEF;"> Unauthorized</span><span>();</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;"> if</span><span> (paused)</span><span style="color: #C678DD;"> revert</span><span style="color: #61AFEF;"> ContractPaused</span><span>();</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #C678DD;"> if</span><span> (value &gt; maxValue)</span><span style="color: #C678DD;"> revert</span><span style="color: #61AFEF;"> InvalidAmount</span><span>();</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #7F848E;font-style: italic;"> // operation logic</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span>}</span></span></code></pre><h2 id="testing-custom-errors">Testing Custom Errors</h2> <p>In Foundry, use <code>vm.expectRevert</code> with the error selector:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> testUnauthorizedAccess</span><span>()</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span> vm.</span><span style="color: #61AFEF;">expectRevert</span><span>(Unauthorized.selector);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span><span> myContract.</span><span style="color: #61AFEF;">restrictedFunction</span><span>();</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">4</span><span>}</span></span></code></pre> <p>For errors with parameters, encode the full expected revert data:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> testInsufficientBalance</span><span>()</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span> vm.</span><span style="color: #61AFEF;">expectRevert</span><span>(</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #E5C07B;"> abi</span><span>.</span><span style="color: #61AFEF;">encodeWithSelector</span><span>(</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span> MyContract.InsufficientBalance.selector,</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #D19A66;"> 0</span><span>,</span><span style="color: #7F848E;font-style: italic;"> // available</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #D19A66;"> 100</span><span style="color: #7F848E;font-style: italic;"> // required</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span> )</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span> );</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span> myContract.</span><span style="color: #61AFEF;">transfer</span><span>(recipient,</span><span style="color: #D19A66;"> 100</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span>}</span></span></code></pre> <p>In Hardhat with Ethers.js, you can match against the error name directly using <code>.revertedWithCustomError()</code>:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="javascript"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #C678DD;">await</span><span style="color: #61AFEF;"> expect</span><span>(</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #E5C07B;"> contract</span><span>.</span><span style="color: #61AFEF;">restrictedFunction</span><span>()</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span><span>).</span><span style="color: #E5C07B;">to</span><span>.</span><span style="color: #E5C07B;">be</span><span>.</span><span style="color: #61AFEF;">revertedWithCustomError</span><span>(</span><span style="color: #E06C75;">contract</span><span>,</span><span style="color: #98C379;"> &quot;Unauthorized&quot;</span><span>);</span></span></code></pre><h2 id="compatibility">Compatibility</h2> <p>Custom errors require Solidity 0.8.4 or later. If your project still targets an earlier compiler version, you cannot use them. Most active projects have moved past 0.8.4, so this is rarely a blocker in practice.</p> <p>Hardhat, Foundry, and Ethers.js all support custom error decoding. Block explorers handle them correctly. The toolchain support is solid.</p> <p>One thing to be aware of: if your contract inherits from external libraries or interfaces that still use <code>require</code> with strings, those strings will still appear in the bytecode from those dependencies. Custom errors only replace the errors you write yourself.</p> <h2 id="migration-strategy">Migration Strategy</h2> <p>If you have an existing contract you want to convert, prioritise the highest-value changes first:</p> <ol> <li>Identify functions that are called frequently or that revert often (access control checks, balance checks, slippage guards).</li> <li>Replace those <code>require</code> statements first.</li> <li>Add parameters to errors where the caller or a frontend needs the failed values to handle the revert properly.</li> <li>Replace the remaining require statements for consistency.</li> </ol> <p>There is no need to convert everything at once. A contract can mix <code>require</code> strings and custom errors. The two approaches are compatible at the bytecode level.</p> <h2 id="summary">Summary</h2> <p>Custom errors are a simple, low-effort optimisation with real impact. Deployment costs drop because string bytecode is replaced by 4-byte selectors. Runtime costs drop because revert data is smaller. Code clarity improves because error names are precise and reusable across functions.</p> <p>The pattern is well-supported across the Solidity toolchain and has become standard practice in modern contract development. If you are writing new contracts or have the opportunity to audit existing ones, switching to custom errors is one of the easiest improvements you can make.</p> 2025-10-20T00:00:00+00:00 2025-10-20T00:00:00+00:00 Akash Vaghela https://akash11.com/blog/solidity-error-handling-require-revert-assert-custom-errors/ <p>Solidity gives you four ways to stop execution when something goes wrong: <code>require</code>, <code>revert</code>, <code>assert</code>, and custom errors. Each one serves a different purpose. Using the wrong one does not break your contract, but it makes your code harder to read and costs more gas than necessary.</p> <p>This post explains what each mechanism does, when to reach for it, and how they compare in terms of gas cost.</p> <h2 id="what-happens-when-an-error-fires">What Happens When an Error Fires</h2> <p>Before Solidity 0.8.0, failed operations could silently continue or produce unpredictable results. That changed in 0.8.0. Now, all four error mechanisms do the same thing at the EVM level: they revert the transaction, roll back every state change made during that call, and refund the remaining gas to the caller.</p> <p>The difference between them is not what they do when they fail, it is what they signal to readers of your code, and how much gas the failure itself costs.</p> <h2 id="require-validate-inputs-and-preconditions">require: Validate Inputs and Preconditions</h2> <p>Use <code>require</code> to check conditions that depend on external input or state that your contract does not control. The pattern is: if this condition is not met, there is no point continuing.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> withdraw</span><span>(</span><span style="color: #E5C07B;">uint</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>)</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;"> require</span><span>(amount &gt;</span><span style="color: #D19A66;"> 0</span><span>,</span><span style="color: #98C379;"> &quot;Amount must be positive&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #C678DD;"> require</span><span>(balance[</span><span style="color: #E5C07B;">msg.sender</span><span>] &gt;</span><span style="color: #56B6C2;">=</span><span> amount,</span><span style="color: #98C379;"> &quot;Insufficient balance&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span> balance[</span><span style="color: #E5C07B;">msg.sender</span><span>]</span><span style="color: #56B6C2;"> -=</span><span> amount;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span> (</span><span style="color: #E5C07B;">bool</span><span> success, )</span><span style="color: #56B6C2;"> =</span><span style="color: #E5C07B;"> msg.sender</span><span>.call{value: amount}(</span><span style="color: #98C379;">&quot;&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #C678DD;"> require</span><span>(success,</span><span style="color: #98C379;"> &quot;Transfer failed&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span>}</span></span></code></pre> <p>The first two <code>require</code> calls validate inputs before any state is modified. The third one verifies the result of an external call after it returns. All three are valid uses.</p> <p>When <code>require</code> fails, it reverts the transaction and returns the error string to the caller. This string is what appears in most wallets and block explorers when a transaction fails.</p> <p>Good places to use <code>require</code>:</p> <ul> <li>Checking <code>msg.sender</code>, <code>msg.value</code>, or function arguments</li> <li>Verifying return values from external calls (<code>token.transfer</code>, <code>call</code>, etc.)</li> <li>Enforcing access control at the start of a function</li> </ul> <h2 id="revert-explicit-control-flow">revert: Explicit Control Flow</h2> <p><code>revert</code> does the same thing as a failing <code>require</code>, it stops execution and rolls back state. The difference is where you can place it.</p> <p><code>require</code> works well at the top of a function where you can check a single condition. Inside nested <code>if</code> statements, it gets awkward. <code>revert</code> fits naturally there.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> buyTicket</span><span>(</span><span style="color: #E5C07B;">uint</span><span style="color: #E06C75;font-style: italic;"> ticketId</span><span>)</span><span style="color: #C678DD;"> public payable</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;"> if</span><span> (</span><span style="color: #E5C07B;">msg</span><span>.value &lt; ticketPrice) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #C678DD;"> revert</span><span>(</span><span style="color: #98C379;">&quot;Payment too low&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #C678DD;"> if</span><span> (tickets[ticketId].sold) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #C678DD;"> revert</span><span>(</span><span style="color: #98C379;">&quot;Ticket already sold&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span> tickets[ticketId].owner </span><span style="color: #56B6C2;">=</span><span style="color: #E5C07B;"> msg.sender</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span> tickets[ticketId].sold </span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> true</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span>}</span></span></code></pre> <p>You can also call <code>revert()</code> without a message. This saves a small amount of gas because no string is encoded into the revert data. The tradeoff is that the caller gets no information about what went wrong, useful only in cases where the revert reason is obvious from context.</p> <h2 id="assert-internal-invariant-checks">assert: Internal Invariant Checks</h2> <p><code>assert</code> is for conditions that should never be false if your contract logic is correct. It checks internal invariants, not user inputs, not external state, but properties that your own code must maintain.</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">function</span><span style="color: #61AFEF;"> transfer</span><span>(</span><span style="color: #E5C07B;">address</span><span style="color: #E06C75;font-style: italic;"> to</span><span>,</span><span style="color: #E5C07B;"> uint</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>)</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #E5C07B;"> uint</span><span> senderBefore </span><span style="color: #56B6C2;">=</span><span> balance[</span><span style="color: #E5C07B;">msg.sender</span><span>];</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span><span style="color: #E5C07B;"> uint</span><span> recipientBefore </span><span style="color: #56B6C2;">=</span><span> balance[to];</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span> balance[</span><span style="color: #E5C07B;">msg.sender</span><span>]</span><span style="color: #56B6C2;"> -=</span><span> amount;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span> balance[to]</span><span style="color: #56B6C2;"> +=</span><span> amount;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #7F848E;font-style: italic;"> // Total balance must be conserved</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #C678DD;"> assert</span><span>(balance[</span><span style="color: #E5C07B;">msg.sender</span><span>]</span><span style="color: #56B6C2;"> +</span><span> balance[to] == senderBefore </span><span style="color: #56B6C2;">+</span><span> recipientBefore);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span>}</span></span></code></pre> <p>If an <code>assert</code> fires in production, it means your contract has a bug. It is not for validating user input. It is a signal to yourself and to auditors: "this must always be true, if it is not, something is fundamentally broken."</p> <blockquote class="markdown-alert-warning"> <p>Before Solidity 0.8.0, a failed <code>assert</code> consumed all remaining gas. In 0.8.0 and later, it behaves like <code>require</code> in terms of gas refunds. If you are working with older contracts, be aware of this difference.</p> </blockquote> <h2 id="custom-errors-gas-efficient-error-handling">Custom Errors: Gas-Efficient Error Handling</h2> <p>Custom errors were introduced in Solidity 0.8.4. They give you the control of <code>revert</code> with significantly lower gas cost compared to string-based errors.</p> <p>Define them at the file or contract level, then use them with <code>revert</code>:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="Wallet.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #C678DD;">error</span><span style="color: #E5C07B;"> InsufficientBalance</span><span>(</span><span style="color: #E5C07B;">uint</span><span> available,</span><span style="color: #E5C07B;"> uint</span><span> requested);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;">error</span><span style="color: #E5C07B;"> Unauthorized</span><span>(</span><span style="color: #E5C07B;">address</span><span> caller);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Wallet</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #C678DD;"> mapping</span><span>(</span><span style="color: #E5C07B;">address</span><span> =&gt;</span><span style="color: #E5C07B;"> uint</span><span>)</span><span style="color: #C678DD;"> public</span><span> balance;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span><span style="color: #E5C07B;"> address</span><span style="color: #C678DD;"> public</span><span> owner;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> withdraw</span><span>(</span><span style="color: #E5C07B;">uint</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>)</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #C678DD;"> if</span><span> (</span><span style="color: #E5C07B;">msg.sender</span><span> != owner) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #C678DD;"> revert</span><span style="color: #61AFEF;"> Unauthorized</span><span>(</span><span style="color: #E5C07B;">msg.sender</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span style="color: #C678DD;"> if</span><span> (balance[</span><span style="color: #E5C07B;">msg.sender</span><span>] &lt; amount) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span style="color: #C678DD;"> revert</span><span style="color: #61AFEF;"> InsufficientBalance</span><span>(balance[</span><span style="color: #E5C07B;">msg.sender</span><span>], amount);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">17</span><span> balance[</span><span style="color: #E5C07B;">msg.sender</span><span>]</span><span style="color: #56B6C2;"> -=</span><span> amount;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">18</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">19</span><span>}</span></span></code></pre> <p>Custom errors can carry parameters. When the transaction reverts, the caller receives typed data, the exact values that caused the failure, rather than a plain string. This makes debugging easier on both the contract side and the frontend side.</p> <p>The gas saving comes from how Solidity encodes errors. A string like <code>"Insufficient balance"</code> is stored in the contract bytecode and encoded into the revert data at runtime. A custom error uses a 4-byte selector (the first four bytes of the keccak256 hash of the error signature), plus ABI-encoded parameters. This is significantly cheaper, especially for errors with long messages.</p> <p>Custom errors cost roughly 2,000 gas less than an equivalent <code>require</code> with a string message. For a function called thousands of times per day, that is real money.</p> <h2 id="choosing-the-right-tool">Choosing the Right Tool</h2> <table><thead><tr><th>Mechanism</th><th>Use when</th></tr></thead><tbody> <tr><td><code>require</code></td><td>Validating inputs, checking preconditions, verifying external call results</td></tr> <tr><td><code>revert</code></td><td>Complex conditional logic where <code>require</code> would be awkward</td></tr> <tr><td><code>assert</code></td><td>Checking invariants that must always hold if your code is correct</td></tr> <tr><td>Custom errors</td><td>Production contracts where gas efficiency matters</td></tr> </tbody></table> <p>In most new contracts, the pattern is: <code>require</code> for simple preconditions at function entry, custom errors with <code>revert</code> for everything else, and <code>assert</code> sparingly for internal consistency checks.</p> <h2 id="a-complete-example">A Complete Example</h2> <p>This contract combines all four mechanisms in realistic ways:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity" data-name="Vault.sol"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 1</span><span style="color: #7F848E;font-style: italic;">// SPDX-License-Identifier: MIT</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 2</span><span style="color: #C678DD;">pragma</span><span style="color: #E06C75;"> solidity</span><span style="color: #D19A66;"> ^0.8.4</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 4</span><span style="color: #C678DD;">error</span><span style="color: #E5C07B;"> NotOwner</span><span>();</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 5</span><span style="color: #C678DD;">error</span><span style="color: #E5C07B;"> InsufficientFunds</span><span>(</span><span style="color: #E5C07B;">uint</span><span> available,</span><span style="color: #E5C07B;"> uint</span><span> requested);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 6</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 7</span><span style="color: #C678DD;">contract</span><span style="color: #E5C07B;"> Vault</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 8</span><span style="color: #E5C07B;"> address</span><span style="color: #C678DD;"> public</span><span> owner;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;"> 9</span><span style="color: #C678DD;"> mapping</span><span>(</span><span style="color: #E5C07B;">address</span><span> =&gt;</span><span style="color: #E5C07B;"> uint</span><span>)</span><span style="color: #C678DD;"> public</span><span> balances;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">10</span><span style="color: #E5C07B;"> uint</span><span style="color: #C678DD;"> public</span><span> totalDeposited;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">11</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">12</span><span style="color: #C678DD;"> constructor</span><span>() {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">13</span><span> owner </span><span style="color: #56B6C2;">=</span><span style="color: #E5C07B;"> msg.sender</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">14</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">15</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">16</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> deposit</span><span>()</span><span style="color: #C678DD;"> public payable</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">17</span><span style="color: #7F848E;font-style: italic;"> // require: validates external input (msg.value)</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">18</span><span style="color: #C678DD;"> require</span><span>(</span><span style="color: #E5C07B;">msg</span><span>.value &gt;</span><span style="color: #D19A66;"> 0</span><span>,</span><span style="color: #98C379;"> &quot;Must deposit something&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">19</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">20</span><span> balances[</span><span style="color: #E5C07B;">msg.sender</span><span>]</span><span style="color: #56B6C2;"> +=</span><span style="color: #E5C07B;"> msg</span><span>.value;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">21</span><span> totalDeposited </span><span style="color: #56B6C2;">+=</span><span style="color: #E5C07B;"> msg</span><span>.value;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">22</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">23</span><span style="color: #7F848E;font-style: italic;"> // assert: verifies internal invariant, contract balance must match our accounting</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">24</span><span style="color: #C678DD;"> assert</span><span>(</span><span style="color: #E5C07B;">address</span><span>(</span><span style="color: #E5C07B;">this</span><span>).balance == totalDeposited);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">25</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">26</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">27</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> withdraw</span><span>(</span><span style="color: #E5C07B;">uint</span><span style="color: #E06C75;font-style: italic;"> amount</span><span>)</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">28</span><span style="color: #7F848E;font-style: italic;"> // custom error with revert: gas-efficient, carries typed context</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">29</span><span style="color: #C678DD;"> if</span><span> (balances[</span><span style="color: #E5C07B;">msg.sender</span><span>] &lt; amount) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">30</span><span style="color: #C678DD;"> revert</span><span style="color: #61AFEF;"> InsufficientFunds</span><span>(balances[</span><span style="color: #E5C07B;">msg.sender</span><span>], amount);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">31</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">32</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">33</span><span> balances[</span><span style="color: #E5C07B;">msg.sender</span><span>]</span><span style="color: #56B6C2;"> -=</span><span> amount;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">34</span><span> totalDeposited </span><span style="color: #56B6C2;">-=</span><span> amount;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">35</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">36</span><span> (</span><span style="color: #E5C07B;">bool</span><span> success, )</span><span style="color: #56B6C2;"> =</span><span style="color: #E5C07B;"> msg.sender</span><span>.call{value: amount}(</span><span style="color: #98C379;">&quot;&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">37</span><span style="color: #7F848E;font-style: italic;"> // require: verifies result of external call</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">38</span><span style="color: #C678DD;"> require</span><span>(success,</span><span style="color: #98C379;"> &quot;Transfer failed&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">39</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">40</span><span style="color: #C678DD;"> assert</span><span>(</span><span style="color: #E5C07B;">address</span><span>(</span><span style="color: #E5C07B;">this</span><span>).balance == totalDeposited);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">41</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">42</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">43</span><span style="color: #C678DD;"> function</span><span style="color: #61AFEF;"> emergencyWithdraw</span><span>()</span><span style="color: #C678DD;"> public</span><span> {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">44</span><span style="color: #7F848E;font-style: italic;"> // custom error: cheap, precise</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">45</span><span style="color: #C678DD;"> if</span><span> (</span><span style="color: #E5C07B;">msg.sender</span><span> != owner) {</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">46</span><span style="color: #C678DD;"> revert</span><span style="color: #61AFEF;"> NotOwner</span><span>();</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">47</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">48</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">49</span><span style="color: #E5C07B;"> uint</span><span> contractBalance </span><span style="color: #56B6C2;">=</span><span style="color: #E5C07B;"> address</span><span>(</span><span style="color: #E5C07B;">this</span><span>).balance;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">50</span><span> totalDeposited </span><span style="color: #56B6C2;">=</span><span style="color: #D19A66;"> 0</span><span>;</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">51</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">52</span><span> (</span><span style="color: #E5C07B;">bool</span><span> success, )</span><span style="color: #56B6C2;"> =</span><span> owner.call{value: contractBalance}(</span><span style="color: #98C379;">&quot;&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">53</span><span style="color: #C678DD;"> require</span><span>(success,</span><span style="color: #98C379;"> &quot;Emergency withdrawal failed&quot;</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">54</span><span> }</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">55</span><span>}</span></span></code></pre> <p>Notice that <code>assert</code> appears after state changes, not before. That is intentional. <code>assert</code> checks that the state your code just produced is internally consistent. It is not a replacement for <code>require</code> at the start of a function.</p> <h2 id="one-pattern-to-avoid">One Pattern to Avoid</h2> <p>A common mistake is using <code>assert</code> for input validation:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="solidity"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #7F848E;font-style: italic;">// Wrong, this is input validation, not an invariant</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #C678DD;">assert</span><span>(</span><span style="color: #E5C07B;">msg</span><span>.value &gt;</span><span style="color: #D19A66;"> 0</span><span>);</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">4</span><span style="color: #7F848E;font-style: italic;">// Correct</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">5</span><span style="color: #C678DD;">require</span><span>(</span><span style="color: #E5C07B;">msg</span><span>.value &gt;</span><span style="color: #D19A66;"> 0</span><span>,</span><span style="color: #98C379;"> &quot;Must send ETH&quot;</span><span>);</span></span></code></pre> <p>The practical consequence in pre-0.8.0 contracts: a failed <code>assert</code> would burn all remaining gas. Even in 0.8.0+, using <code>assert</code> for input validation signals to auditors that you either misunderstand the distinction or have a logic error you are trying to catch. Neither is a good look.</p> <h2 id="summary">Summary</h2> <p>Solidity's four error mechanisms share the same outcome, transaction revert, but communicate different things:</p> <ul> <li><code>require</code> says "the caller did something wrong or the external state is not ready"</li> <li><code>revert</code> says "a condition was not met, and I need explicit control over when to stop"</li> <li><code>assert</code> says "my contract's internal state is broken, this should never happen"</li> <li>Custom errors say all of the above, with less gas and better typed data for callers</li> </ul> <p>Use each for what it was designed for. The distinction matters most when someone else is reading your code, or when an auditor is trying to understand what your contract assumes about the world.</p> 2025-08-11T00:00:00+00:00 2025-08-11T00:00:00+00:00 Akash Vaghela https://akash11.com/blog/managing-multiple-node-versions-with-nvm/ <p>If you work on more than one JavaScript project, you have probably hit this problem: one project needs Node 16, another needs Node 20, and the system only has one version installed.</p> <p>Reinstalling Node every time you switch projects is not a real solution. Node Version Manager (NVM) is. It lets you install multiple Node.js versions on the same machine and switch between them per project or per terminal session.</p> <p>This post walks through installing NVM, the commands you will use daily, and how to lock versions per project so your whole team stays in sync.</p> <h2 id="installing-nvm">Installing NVM</h2> <p>Before installing NVM, remove any existing system-wide Node.js installation. A leftover installation can cause PATH conflicts where commands resolve to the wrong binary.</p> <h3 id="macos-and-linux">macOS and Linux</h3> <p>Run the install script using curl:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #61AFEF;">curl</span><span style="color: #D19A66;"> -o-</span><span style="color: #98C379;"> https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh</span><span> |</span><span style="color: #61AFEF;"> bash</span></span></code></pre> <p>Or with wget if you prefer:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #61AFEF;">wget</span><span style="color: #D19A66;"> -qO-</span><span style="color: #98C379;"> https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh</span><span> |</span><span style="color: #61AFEF;"> bash</span></span></code></pre> <p>The script adds initialization code to your shell profile automatically. After it finishes, reload your shell:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #7F848E;font-style: italic;"># For bash</span></span> <span class="giallo-l"><span style="color: #56B6C2;">source</span><span style="color: #98C379;"> ~/.bashrc</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #7F848E;font-style: italic;"># For zsh</span></span> <span class="giallo-l"><span style="color: #56B6C2;">source</span><span style="color: #98C379;"> ~/.zshrc</span></span></code></pre> <p>Verify the installation worked:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #61AFEF;">nvm</span><span style="color: #D19A66;"> --version</span></span></code></pre><h3 id="windows">Windows</h3> <p>NVM does not support Windows natively. A separate project called <code>nvm-windows</code> covers this. Download the installer from <a rel="noopener noreferrer external" target="_blank" href="https://github.com/coreybutler/nvm-windows/releases">github.com/coreybutler/nvm-windows/releases</a>, run it, and follow the wizard.</p> <blockquote class="markdown-alert-note"> <p><code>nvm-windows</code> has slightly different command names from the macOS/Linux version. The core workflow is the same, but a few commands differ. This post focuses on macOS/Linux. Where Windows commands differ, they are noted.</p> </blockquote> <h2 id="installing-node-js-versions">Installing Node.js Versions</h2> <p>Once NVM is set up, installing a Node version is one command.</p> <p>Install the current LTS release:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #61AFEF;">nvm</span><span style="color: #98C379;"> install</span><span style="color: #D19A66;"> --lts</span></span></code></pre> <p>Install a specific version:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #61AFEF;">nvm</span><span style="color: #98C379;"> install</span><span style="color: #D19A66;"> 18.17.0</span></span></code></pre> <p>Install the latest release (whatever is newest at the time):</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #61AFEF;">nvm</span><span style="color: #98C379;"> install node</span></span></code></pre> <p>NVM downloads the binary, stores it in <code>~/.nvm/versions/</code>, and makes it active in the current terminal session.</p> <p>To see every available version:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #7F848E;font-style: italic;"># macOS / Linux</span></span> <span class="giallo-l"><span style="color: #61AFEF;">nvm</span><span style="color: #98C379;"> ls-remote</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #7F848E;font-style: italic;"># Windows</span></span> <span class="giallo-l"><span style="color: #61AFEF;">nvm</span><span style="color: #98C379;"> list available</span></span></code></pre> <p>The output is long. Filter it with <code>grep</code>:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #61AFEF;">nvm</span><span style="color: #98C379;"> ls-remote</span><span> |</span><span style="color: #61AFEF;"> grep</span><span style="color: #98C379;"> &quot;v20&quot;</span></span></code></pre><h2 id="switching-versions">Switching Versions</h2> <p>This is the main use case. Switch to a specific version:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #61AFEF;">nvm</span><span style="color: #98C379;"> use</span><span style="color: #D19A66;"> 18.17.0</span></span></code></pre> <p>Switch to the latest LTS:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #61AFEF;">nvm</span><span style="color: #98C379;"> use</span><span style="color: #D19A66;"> --lts</span></span></code></pre> <p>The change applies to the current terminal session only. Open a new terminal and you are back to whatever the default is.</p> <h3 id="setting-a-default-version">Setting a Default Version</h3> <p>To avoid running <code>nvm use</code> every time you open a terminal, set a default:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #61AFEF;">nvm</span><span style="color: #98C379;"> alias default</span><span style="color: #D19A66;"> 18.17.0</span></span></code></pre> <p>Every new session will start with Node 18.17.0 active.</p> <h2 id="essential-commands">Essential Commands</h2> <p>List all installed versions:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #61AFEF;">nvm</span><span style="color: #98C379;"> ls</span></span></code></pre> <p>The output shows installed versions and marks the active one:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="plain"><span class="giallo-l"><span> v16.20.2</span></span> <span class="giallo-l"><span>-&gt; v18.17.0</span></span> <span class="giallo-l"><span> v20.10.0</span></span> <span class="giallo-l"><span>default -&gt; 18.17.0 (-&gt; v18.17.0)</span></span></code></pre> <p>Check what is currently active:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #61AFEF;">nvm</span><span style="color: #98C379;"> current</span></span></code></pre> <p>Run a command using a specific version without switching your session:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #61AFEF;">nvm</span><span style="color: #98C379;"> exec</span><span style="color: #D19A66;"> 16.20.2</span><span style="color: #98C379;"> node app.js</span></span></code></pre> <p>This is useful for one-off checks or running scripts that need a specific version while you keep working on another.</p> <p>Find the binary path for a version:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #61AFEF;">nvm</span><span style="color: #98C379;"> which</span><span style="color: #D19A66;"> 18.17.0</span></span></code></pre> <p>Output:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="plain"><span class="giallo-l"><span>/Users/username/.nvm/versions/node/v18.17.0/bin/node</span></span></code></pre> <p>Uninstall a version:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #61AFEF;">nvm</span><span style="color: #98C379;"> uninstall</span><span style="color: #D19A66;"> 16.20.2</span></span></code></pre> <blockquote class="markdown-alert-warning"> <p>Uninstalling a version also removes all globally installed packages for that version. Make a note of what you have installed globally before removing a version.</p> </blockquote> <h2 id="project-specific-version-control-with-nvmrc">Project-Specific Version Control with <code>.nvmrc</code></h2> <p>The real productivity gain comes from locking Node versions per project. Create an <code>.nvmrc</code> file in your project root:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="shellscript" data-name=".nvmrc"><span class="giallo-l"><span style="color: #61AFEF;">18.17.0</span></span></code></pre> <p>Or generate it from the command line:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #56B6C2;">echo</span><span style="color: #98C379;"> &quot;18.17.0&quot;</span><span> &gt;</span><span style="color: #98C379;"> .nvmrc</span></span></code></pre> <p>When you or a teammate clones the repo and runs <code>nvm use</code> from the project directory, NVM reads the file and switches to the correct version automatically. No version arguments needed.</p> <p>This eliminates the "works on my machine" problem caused by different team members running different Node versions.</p> <h3 id="auto-switching-on-directory-change">Auto-Switching on Directory Change</h3> <p>You can go one step further and have NVM switch versions automatically whenever you <code>cd</code> into a directory that has an <code>.nvmrc</code>. Add this to your <code>~/.zshrc</code>:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="shellscript" data-name="~/.zshrc"><span class="giallo-l"><span style="color: #56B6C2;">autoload</span><span style="color: #D19A66;"> -U</span><span style="color: #98C379;"> add-zsh-hook</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #61AFEF;">load-nvmrc</span><span>() {</span></span> <span class="giallo-l"><span style="color: #C678DD;"> if</span><span> [[</span><span style="color: #56B6C2;"> -f</span><span> .nvmrc </span><span style="color: #56B6C2;">&amp;&amp; -r</span><span> .nvmrc ]];</span><span style="color: #C678DD;"> then</span></span> <span class="giallo-l"><span style="color: #61AFEF;"> nvm</span><span style="color: #98C379;"> use</span></span> <span class="giallo-l"><span style="color: #C678DD;"> fi</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #61AFEF;">add-zsh-hook</span><span style="color: #98C379;"> chdir load-nvmrc</span></span></code></pre> <p>After reloading your shell, entering a directory with <code>.nvmrc</code> triggers <code>nvm use</code> without any manual step.</p> <h2 id="managing-global-packages-across-versions">Managing Global Packages Across Versions</h2> <p>Each Node version has its own isolated set of global packages. If you install <code>nodemon</code> globally on Node 18, it will not exist on Node 20.</p> <p>Install a global package for the current version:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #61AFEF;">npm</span><span style="color: #98C379;"> install</span><span style="color: #D19A66;"> -g</span><span style="color: #98C379;"> nodemon</span></span></code></pre> <p>When you upgrade to a new Node version, you can carry global packages over:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #61AFEF;">nvm</span><span style="color: #98C379;"> install</span><span style="color: #D19A66;"> 20.10.0 --reinstall-packages-from=18.17.0</span></span></code></pre> <p>This installs Node 20.10.0 and copies all global packages from 18.17.0 to the new version.</p> <p>View the global packages for your current version:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #61AFEF;">npm</span><span style="color: #98C379;"> list</span><span style="color: #D19A66;"> -g --depth=0</span></span></code></pre><h2 id="troubleshooting">Troubleshooting</h2> <h3 id="nvm-command-not-found"><code>nvm: command not found</code></h3> <p>The shell cannot locate NVM. The install script should have added initialization lines to your profile, but sometimes it does not. Check your <code>~/.bashrc</code>, <code>~/.zshrc</code>, or <code>~/.profile</code> for these lines:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #C678DD;">export</span><span style="color: #E06C75;"> NVM_DIR</span><span style="color: #56B6C2;">=</span><span style="color: #98C379;">&quot;</span><span style="color: #E06C75;">$HOME</span><span style="color: #98C379;">/.nvm&quot;</span></span> <span class="giallo-l"><span>[</span><span style="color: #56B6C2;"> -s</span><span style="color: #98C379;"> &quot;</span><span style="color: #E06C75;">$NVM_DIR</span><span style="color: #98C379;">/nvm.sh&quot;</span><span> ] &amp;&amp;</span><span style="color: #61AFEF;"> \.</span><span style="color: #98C379;"> &quot;</span><span style="color: #E06C75;">$NVM_DIR</span><span style="color: #98C379;">/nvm.sh&quot;</span></span></code></pre> <p>If they are missing, add them manually and run <code>source ~/.bashrc</code> or <code>source ~/.zshrc</code>.</p> <h3 id="slow-terminal-startup">Slow Terminal Startup</h3> <p>NVM loads on every shell init, which adds a small delay. You can defer that load until you first use NVM by replacing the standard init lines with this lazy-loading version:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="shellscript" data-name="~/.zshrc"><span class="giallo-l"><span style="color: #61AFEF;">nvm</span><span>() {</span></span> <span class="giallo-l"><span style="color: #56B6C2;"> unset</span><span style="color: #D19A66;"> -f</span><span style="color: #98C379;"> nvm</span></span> <span class="giallo-l"><span style="color: #C678DD;"> export</span><span style="color: #E06C75;"> NVM_DIR</span><span style="color: #56B6C2;">=</span><span style="color: #98C379;">&quot;</span><span style="color: #E06C75;">$HOME</span><span style="color: #98C379;">/.nvm&quot;</span></span> <span class="giallo-l"><span> [</span><span style="color: #56B6C2;"> -s</span><span style="color: #98C379;"> &quot;</span><span style="color: #E06C75;">$NVM_DIR</span><span style="color: #98C379;">/nvm.sh&quot;</span><span> ] &amp;&amp;</span><span style="color: #61AFEF;"> \.</span><span style="color: #98C379;"> &quot;</span><span style="color: #E06C75;">$NVM_DIR</span><span style="color: #98C379;">/nvm.sh&quot;</span></span> <span class="giallo-l"><span style="color: #61AFEF;"> nvm</span><span style="color: #98C379;"> &quot;</span><span style="color: #E06C75;font-style: italic;">$@</span><span style="color: #98C379;">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>NVM loads the first time you call it, not when the shell starts.</p> <h3 id="version-not-persisting-across-terminals">Version Not Persisting Across Terminals</h3> <p>You have not set a default. Fix it with:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #61AFEF;">nvm</span><span style="color: #98C379;"> alias default</span><span style="color: #D19A66;"> 18.17.0</span></span></code></pre><h3 id="permission-errors-on-linux">Permission Errors on Linux</h3> <p>Never run NVM commands with <code>sudo</code>. NVM is designed to run as your user, and using <code>sudo</code> breaks the permission model. If you are hitting permission errors, the likely cause is that <code>~/.nvm</code> was created with wrong ownership. Fix it:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #61AFEF;">sudo</span><span style="color: #98C379;"> chown</span><span style="color: #D19A66;"> -R</span><span style="color: #E06C75;"> $USER</span><span style="color: #98C379;">:</span><span style="color: #E06C75;">$USER</span><span style="color: #98C379;"> ~/.nvm</span></span></code></pre><h2 id="keeping-nvm-up-to-date">Keeping NVM Up to Date</h2> <p>NVM does not have an <code>nvm update</code> command. To upgrade, re-run the install script with the new version number in the URL. Check the <a rel="noopener noreferrer external" target="_blank" href="https://github.com/nvm-sh/nvm/releases">NVM GitHub releases</a> for the latest version, then run:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #61AFEF;">curl</span><span style="color: #D19A66;"> -o-</span><span style="color: #98C379;"> https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh</span><span> |</span><span style="color: #61AFEF;"> bash</span></span></code></pre> <p>Replace <code>v0.39.7</code> with the current release. The script is safe to re-run on an existing installation.</p> <h2 id="wrapping-up">Wrapping Up</h2> <p>NVM reduces multi-version Node.js management to a handful of commands. The core workflow is:</p> <ul> <li><code>nvm install &lt;version&gt;</code> to get a version</li> <li><code>nvm use &lt;version&gt;</code> to activate it in the current session</li> <li><code>nvm alias default &lt;version&gt;</code> to set a permanent default</li> <li><code>.nvmrc</code> files to lock versions per project</li> </ul> <p>One thing to keep in mind: global packages are version-specific. When you install a new Node version, reinstall or migrate your globals. It is a small cost for a development environment that stays predictable across projects and machines.</p> 2025-06-14T00:00:00+00:00 2025-06-14T00:00:00+00:00 Akash Vaghela https://akash11.com/blog/fix-grub-dual-boot-ubuntu-windows/ <p>You set up Ubuntu and Windows on the same machine. Everything worked. Then Windows pushed an update, and now your system boots straight into Windows. Ubuntu is gone from the menu. Maybe you saw this before it gave up:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="plain"><span class="giallo-l"><span>Failed to open \EFI\UBUNTU\grubx64.efi - Not Found</span></span> <span class="giallo-l"><span>Failed to load image \EFI\UBUNTU\grubx64.efi: Not Found</span></span> <span class="giallo-l"><span>start_image() returned Not Found, falling back to default loader</span></span></code></pre> <p>Your Ubuntu installation is still on the disk. Nothing was deleted. The problem is that Windows overwrote the GRUB bootloader files in the EFI System Partition. This guide shows you how to restore them using a live Ubuntu USB drive.</p> <hr /> <h2 id="what-happened-and-why">What Happened and Why</h2> <p>When you boot a modern computer, the firmware reads from a special partition called the <strong>EFI System Partition</strong> (ESP). This FAT32 partition contains bootloader files for every operating system installed. When you installed Ubuntu, it placed GRUB's files at <code>\EFI\UBUNTU\grubx64.efi</code> inside that partition.</p> <p>Windows updates sometimes overwrite or reset the default EFI boot entry to point only to the Windows Boot Manager. In some cases, they delete Ubuntu's EFI files entirely. Either way, the result is the same: GRUB is gone from the boot sequence, and Ubuntu never starts.</p> <p>The fix is to boot from a live Ubuntu USB, mount your existing Ubuntu installation, and reinstall GRUB into the correct location.</p> <blockquote class="markdown-alert-important"> <p>This process does not touch your Ubuntu or Windows data partitions. You will not lose files. The only thing you are modifying is the bootloader in the EFI partition.</p> </blockquote> <hr /> <h2 id="what-you-need">What You Need</h2> <ul> <li>A bootable Ubuntu USB drive (the same version or newer than your installed Ubuntu)</li> <li>About 10 to 15 minutes</li> </ul> <p>If you do not have a live USB ready, create one using <a rel="noopener noreferrer external" target="_blank" href="https://etcher.balena.io/">Balena Etcher</a> or the Ubuntu Startup Disk Creator.</p> <hr /> <h2 id="step-1-boot-into-the-live-usb">Step 1: Boot into the Live USB</h2> <p>Insert the USB drive and restart your computer. As it powers on, press the boot menu key for your machine. This is usually <code>F12</code>, <code>F10</code>, <code>Esc</code>, or <code>Del</code>, depending on your motherboard manufacturer.</p> <p>Select your USB drive from the boot menu. When the Ubuntu installer appears, choose <strong>Try Ubuntu</strong> (not "Install Ubuntu"). This loads a temporary Ubuntu session without touching your disk.</p> <hr /> <h2 id="step-2-open-a-terminal">Step 2: Open a Terminal</h2> <p>Once the desktop loads, press <code>Ctrl + Alt + T</code> to open a terminal. All the following commands run here.</p> <hr /> <h2 id="step-3-find-your-partitions">Step 3: Find Your Partitions</h2> <p>You need to identify two partitions:</p> <ul> <li>Your <strong>Ubuntu root partition</strong> (the one formatted as ext4 that contains your Ubuntu installation)</li> <li>Your <strong>EFI System Partition</strong> (a small FAT32 partition, usually 100 to 512 MB)</li> </ul> <p>Run:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #61AFEF;">sudo</span><span style="color: #98C379;"> fdisk</span><span style="color: #D19A66;"> -l</span></span></code></pre> <p>The output lists every disk and partition. Look for something like this:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="plain"><span class="giallo-l"><span>Device Start End Sectors Size Type</span></span> <span class="giallo-l"><span>/dev/nvme0n1p1 2048 534527 532480 260M EFI System</span></span> <span class="giallo-l"><span>/dev/nvme0n1p2 534528 796671 262144 128M Microsoft reserved</span></span> <span class="giallo-l"><span>/dev/nvme0n1p3 796672 209559551 208762880 99.6G Microsoft basic data</span></span> <span class="giallo-l"><span>/dev/nvme0n1p4 209559552 500117503 290557952 138.6G Linux filesystem</span></span></code></pre> <p>In this example, <code>nvme0n1p1</code> is the EFI partition and <code>nvme0n1p4</code> is the Ubuntu root partition. Your partition names will differ. Note them down before continuing.</p> <blockquote class="markdown-alert-tip"> <p>If you have an older SATA drive instead of NVMe, your partitions will be named like <code>/dev/sda1</code>, <code>/dev/sda2</code>, and so on. The process is identical.</p> </blockquote> <hr /> <h2 id="step-4-mount-the-ubuntu-partition">Step 4: Mount the Ubuntu Partition</h2> <p>Create a mount point and mount your Ubuntu root partition:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="shellscript"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #61AFEF;">sudo</span><span style="color: #98C379;"> mkdir</span><span style="color: #D19A66;"> -p</span><span style="color: #98C379;"> /mnt/ubuntu</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #61AFEF;">sudo</span><span style="color: #98C379;"> mount /dev/nvme0n1p4 /mnt/ubuntu</span></span></code></pre> <p>Replace <code>/dev/nvme0n1p4</code> with your actual Ubuntu partition.</p> <hr /> <h2 id="step-5-mount-the-efi-partition">Step 5: Mount the EFI Partition</h2> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="shellscript"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #61AFEF;">sudo</span><span style="color: #98C379;"> mkdir</span><span style="color: #D19A66;"> -p</span><span style="color: #98C379;"> /mnt/ubuntu/boot/efi</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #61AFEF;">sudo</span><span style="color: #98C379;"> mount /dev/nvme0n1p1 /mnt/ubuntu/boot/efi</span></span></code></pre> <p>Replace <code>/dev/nvme0n1p1</code> with your actual EFI partition.</p> <hr /> <h2 id="step-6-mount-the-required-system-directories">Step 6: Mount the Required System Directories</h2> <p>GRUB needs access to device nodes, process information, and kernel interfaces during reinstallation. These three bind mounts provide that:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="shellscript"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #61AFEF;">sudo</span><span style="color: #98C379;"> mount</span><span style="color: #D19A66;"> --bind</span><span style="color: #98C379;"> /dev /mnt/ubuntu/dev</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #61AFEF;">sudo</span><span style="color: #98C379;"> mount</span><span style="color: #D19A66;"> --bind</span><span style="color: #98C379;"> /proc /mnt/ubuntu/proc</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span><span style="color: #61AFEF;">sudo</span><span style="color: #98C379;"> mount</span><span style="color: #D19A66;"> --bind</span><span style="color: #98C379;"> /sys /mnt/ubuntu/sys</span></span></code></pre> <hr /> <h2 id="step-7-enter-your-installed-ubuntu-system">Step 7: Enter Your Installed Ubuntu System</h2> <p><code>chroot</code> switches your active root directory to the mounted Ubuntu installation. After this command, you are running inside your real Ubuntu system, not the live USB:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #61AFEF;">sudo</span><span style="color: #98C379;"> chroot /mnt/ubuntu</span></span></code></pre> <p>Your terminal prompt will change. Commands you run now affect your installed system, not the live environment.</p> <hr /> <h2 id="step-8-reinstall-grub">Step 8: Reinstall GRUB</h2> <p>Run <code>grub-install</code> targeting the <strong>disk</strong>, not a partition. Then update the GRUB configuration:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="shellscript"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #61AFEF;">grub-install</span><span style="color: #98C379;"> /dev/nvme0n1</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #61AFEF;">update-grub</span></span></code></pre> <p>Replace <code>/dev/nvme0n1</code> with your actual disk identifier. If you are unsure which one to use, run <code>lsblk</code> and look for the root device that contains your partitions. It will not have a number at the end.</p> <p>You should see output similar to:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="plain"><span class="giallo-l"><span>Installing for x86_64-efi platform.</span></span> <span class="giallo-l"><span>Installation finished. No error reported.</span></span> <span class="giallo-l"><span>Generating grub configuration file ...</span></span> <span class="giallo-l"><span>Found linux image: /boot/vmlinuz-6.8.0-60-generic</span></span> <span class="giallo-l"><span>Found Windows Boot Manager on /dev/nvme0n1p1@/EFI/Microsoft/Boot/bootmgfw.efi</span></span> <span class="giallo-l"><span>done</span></span></code></pre> <p>The line confirming Windows Boot Manager was found is important. It means GRUB will include Windows in the boot menu automatically.</p> <blockquote class="markdown-alert-warning"> <p>If <code>grub-install</code> reports an error about not finding an EFI directory or missing packages, make sure the EFI partition is correctly mounted at <code>/mnt/ubuntu/boot/efi</code> and try again. Do not skip to <code>update-grub</code> alone as that does not reinstall the EFI files.</p> </blockquote> <hr /> <h2 id="step-9-exit-and-unmount">Step 9: Exit and Unmount</h2> <p>Exit the chroot environment:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #56B6C2;">exit</span></span></code></pre> <p>Now unmount everything in reverse order:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="shellscript"><span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">1</span><span style="color: #61AFEF;">sudo</span><span style="color: #98C379;"> umount /mnt/ubuntu/dev</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">2</span><span style="color: #61AFEF;">sudo</span><span style="color: #98C379;"> umount /mnt/ubuntu/proc</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">3</span><span style="color: #61AFEF;">sudo</span><span style="color: #98C379;"> umount /mnt/ubuntu/sys</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">4</span><span style="color: #61AFEF;">sudo</span><span style="color: #98C379;"> umount /mnt/ubuntu/boot/efi</span></span> <span class="giallo-l"><span aria-hidden="true" class="giallo-ln" style="color: #495162;">5</span><span style="color: #61AFEF;">sudo</span><span style="color: #98C379;"> umount /mnt/ubuntu</span></span></code></pre> <hr /> <h2 id="step-10-reboot">Step 10: Reboot</h2> <p>Remove the USB drive and restart:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #61AFEF;">sudo</span><span style="color: #98C379;"> reboot</span></span></code></pre> <p>Your system should now show the GRUB menu with both Ubuntu and Windows listed. Select Ubuntu to confirm it boots correctly.</p> <hr /> <h2 id="if-the-problem-comes-back-after-the-next-windows-update">If the Problem Comes Back After the Next Windows Update</h2> <p>Windows has a habit of resetting the EFI boot order after major updates. To reduce the chance of this happening again, you can set GRUB as the default EFI boot entry at the firmware level.</p> <p>After booting back into Ubuntu normally, run:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #61AFEF;">sudo</span><span style="color: #98C379;"> efibootmgr</span><span style="color: #D19A66;"> -v</span></span></code></pre> <p>This lists all EFI boot entries. Look for the entry labelled <code>ubuntu</code> or <code>GRUB</code> and note its boot number (for example, <code>Boot0003</code>). Then set it as the default:</p> <pre class="giallo" style="color: #ABB2BF; background-color: #282C34;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #61AFEF;">sudo</span><span style="color: #98C379;"> efibootmgr</span><span style="color: #D19A66;"> --bootorder</span><span style="color: #98C379;"> 0003,0001,0000</span></span></code></pre> <p>Put the GRUB entry number first in the list. This tells the firmware to always try GRUB before the Windows Boot Manager, making it harder for Windows updates to take over.</p> <p>That said, some machines with aggressive firmware will still reset this. If you dual boot regularly, it is worth checking the boot order after every major Windows update.</p> 2025-06-03T00:00:00+00:00 2025-06-03T00:00:00+00:00 Akash Vaghela https://akash11.com/blog/web3-smart-contract-security-resources/ <p>Smart contract security is a demanding field. You need to understand Solidity, the EVM, DeFi protocols, cryptographic primitives, and how attackers think — all at once.</p> <p>This post collects the resources worth your time. Each section covers a distinct area of knowledge. Work through them in order if you are starting out, or jump to the section you need.</p> <h2 id="solidity-and-the-evm">Solidity and the EVM</h2> <p>Before auditing contracts, you need to read and write Solidity well. These resources cover the language and the execution environment beneath it.</p> <p><strong>Official documentation</strong></p> <ul> <li><a rel="noopener noreferrer external" target="_blank" href="https://docs.soliditylang.org/en/v0.8.30/">Solidity Docs</a> — the authoritative reference for the language</li> <li><a rel="noopener noreferrer external" target="_blank" href="https://solidity-by-example.org/">Solidity by Example</a> — short, focused examples of common patterns</li> </ul> <p><strong>EVM internals</strong></p> <ul> <li><a rel="noopener noreferrer external" target="_blank" href="https://www.decipherclub.com/ethereum-virtual-machine-article-series/">Ethereum Virtual Machine by Zaryab</a> — a readable series on how the EVM actually executes code</li> </ul> <p><strong>Secureum series</strong></p> <p>The Secureum substack is one of the most concentrated sources of Ethereum and Solidity knowledge available. Read these in order:</p> <ul> <li><a rel="noopener noreferrer external" target="_blank" href="https://secureum.substack.com/p/ethereum-101">Ethereum 101</a></li> <li><a rel="noopener noreferrer external" target="_blank" href="https://secureum.substack.com/p/solidity-101">Solidity 101</a></li> <li><a rel="noopener noreferrer external" target="_blank" href="https://secureum.substack.com/p/solidity-201">Solidity 201</a></li> <li><a rel="noopener noreferrer external" target="_blank" href="https://github.com/shanzson/Smart-Contract-Auditor-Tools-and-Techniques?tab=readme-ov-file#ethereum-blogs-to-deep-dive">Ethereum blog deep dives</a></li> </ul> <p><strong>Quick reference</strong></p> <ul> <li><a rel="noopener noreferrer external" target="_blank" href="https://github.com/manojpramesh/solidity-cheatsheet">Solidity Cheatsheet</a></li> <li><a rel="noopener noreferrer external" target="_blank" href="https://topmonks.github.io/solidity_quick_ref/">Solidity Quick Reference</a></li> </ul> <h2 id="foundry">Foundry</h2> <p>Foundry is the standard toolkit for writing tests, running forks, and building proof-of-concept exploits in Solidity. If you are not using it already, start now.</p> <ul> <li><a rel="noopener noreferrer external" target="_blank" href="https://book.getfoundry.sh/">Foundry Book</a> — complete documentation for the toolchain</li> </ul> <h2 id="token-standards-and-eips">Token Standards and EIPs</h2> <p>Auditors spend a lot of time reviewing token contracts. Knowing the standards and their edge cases is not optional.</p> <ul> <li><a rel="noopener noreferrer external" target="_blank" href="https://ethereum.org/en/developers/docs/standards/tokens/">Token Standards: ERC-20, 721, 777, 1155, 4626</a></li> <li><a rel="noopener noreferrer external" target="_blank" href="https://eips.ethereum.org/EIPS/eip-2981">ERC-2981: NFT Royalty Standard</a></li> <li><a rel="noopener noreferrer external" target="_blank" href="https://github.com/abarbatei/weird-erc721">Weird ERC-721 Tokens</a> — a collection of non-standard ERC-721 implementations that break naive assumptions</li> <li><a rel="noopener noreferrer external" target="_blank" href="https://github.com/razzorsec/AuditorsRoadmap?tab=readme-ov-file#16-important-ethereum-improvement-proposals-eips">Important EIPs for Auditors</a></li> </ul> <h2 id="proxy-patterns-and-upgradeable-contracts">Proxy Patterns and Upgradeable Contracts</h2> <p>Proxy contracts are a common source of vulnerabilities. The different patterns each carry different risks.</p> <ul> <li><a rel="noopener noreferrer external" target="_blank" href="https://ethereum-blockchain-developer.com/110-upgrade-smart-contracts/00-project/">Proxy Patterns Overview: EIPs 897, 1822, 1967, 1538, 2535</a></li> <li><a rel="noopener noreferrer external" target="_blank" href="https://github.com/electisec/Solidity-Proxy-Playground">Solidity Proxy Playground</a> — both vulnerable and fixed implementations to study side by side</li> </ul> <h2 id="security-best-practices-and-checklists">Security Best Practices and Checklists</h2> <p>These resources cover what to look for during a review and how to structure your thinking.</p> <ul> <li><a rel="noopener noreferrer external" target="_blank" href="https://secureum.substack.com/p/security-pitfalls-and-best-practices-101">Security Pitfalls and Best Practices 101</a></li> <li><a rel="noopener noreferrer external" target="_blank" href="https://secureum.substack.com/p/security-pitfalls-and-best-practices-201">Security Pitfalls and Best Practices 201</a></li> <li><a rel="noopener noreferrer external" target="_blank" href="https://docs.soliditylang.org/en/latest/security-considerations.html">Solidity Security Considerations</a> — official guidance from the Solidity team</li> <li><a rel="noopener noreferrer external" target="_blank" href="https://github.com/securing/SCSVS/tree/master">Smart Contract Security Verification Standard (SCSVS)</a> — a structured checklist for audits</li> <li><a rel="noopener noreferrer external" target="_blank" href="https://github.com/dragonfly-xyz/useful-solidity-patterns">Useful Solidity Patterns</a> — patterns that help avoid common mistakes</li> <li><a rel="noopener noreferrer external" target="_blank" href="https://github.com/transmissions11/solcurity">The Solcurity Standard</a> — a practical security checklist from the community</li> <li><a rel="noopener noreferrer external" target="_blank" href="https://github.com/Decurity/semgrep-smart-contracts">Semgrep Rules for Smart Contracts</a> — static analysis rules you can run on codebases</li> <li><a rel="noopener noreferrer external" target="_blank" href="https://github.com/OpenCoreCH/smart-contract-auditing-heuristics">Smart Contract Auditing Heuristics</a></li> </ul> <h2 id="defi-knowledge">DeFi Knowledge</h2> <p>Most audit targets are DeFi protocols. Understanding how they work — AMMs, lending markets, derivatives, vaults — is a prerequisite for finding meaningful bugs.</p> <p><strong>Finance foundations</strong></p> <ul> <li><a rel="noopener noreferrer external" target="_blank" href="https://www.khanacademy.org/economics-finance-domain/core-finance/derivative-securities">Khan Academy: Derivatives and Other Securities</a> — start here if you are not familiar with how financial instruments work</li> </ul> <p><strong>DeFi overviews</strong></p> <ul> <li><a rel="noopener noreferrer external" target="_blank" href="https://github.com/OffcierCia/DeFi-Developer-Road-Map/tree/main">DeFi Developer Roadmap</a></li> <li><a rel="noopener noreferrer external" target="_blank" href="https://teachyourselfcrypto.com/#ftoc-module-4-decentralized-finance-defi">Teach Yourself Crypto: DeFi Module</a></li> <li><a rel="noopener noreferrer external" target="_blank" href="https://www.youtube.com/watch?v=pWGLtjG-F5c&amp;list=PLjrTIwaNiTwn39tg3sR_bPBWGHoznv47D">Finematics DeFi Playlist</a> — visual explainers for major DeFi protocols</li> <li><a rel="noopener noreferrer external" target="_blank" href="https://www.youtube.com/watch?v=qB2Ulx201wY&amp;list=PLO5VPQH6OWdX-Rh7RonjZhOd9pb9zOnHW">Smart Contract Programmer DeFi Playlist</a></li> <li><a rel="noopener noreferrer external" target="_blank" href="https://github.com/razzorsec/AuditorsRoadmap?tab=readme-ov-file#11-defi-deep-dive">RazzorSec DeFi Deep Dive</a></li> </ul> <h2 id="vulnerabilities-and-attack-vectors">Vulnerabilities and Attack Vectors</h2> <p>This is the core of security research. Study these to understand what attackers exploit and how.</p> <p><strong>Secureum</strong></p> <ul> <li><a rel="noopener noreferrer external" target="_blank" href="https://secureum.substack.com/p/audit-techniques-and-tools-101">Audit Techniques and Tools 101</a></li> <li><a rel="noopener noreferrer external" target="_blank" href="https://secureum.substack.com/p/audit-findings-101">Audit Findings 101</a></li> <li><a rel="noopener noreferrer external" target="_blank" href="https://secureum.substack.com/p/audit-findings-201">Audit Findings 201</a></li> </ul> <p><strong>Vulnerability databases and lists</strong></p> <ul> <li><a rel="noopener noreferrer external" target="_blank" href="https://github.com/sigp/solidity-security-blog">Solidity Security Blog by sigp</a></li> <li><a rel="noopener noreferrer external" target="_blank" href="https://github.com/kadenzipfel/smart-contract-vulnerabilities">Smart Contract Vulnerabilities</a></li> <li><a rel="noopener noreferrer external" target="_blank" href="https://swcregistry.io/">Smart Contract Weakness Classification (SWC Registry)</a> — structured classification of known weaknesses</li> <li><a rel="noopener noreferrer external" target="_blank" href="https://github.com/harendra-shakya/smart-contract-attack-vectors">Smart Contract Attack Vectors</a></li> <li><a rel="noopener noreferrer external" target="_blank" href="https://github.com/SunWeb3Sec/DeFiVulnLabs/tree/main">DeFiVulnLabs by SunWeb3Sec</a> — live, runnable PoC exploits for known vulnerabilities</li> <li><a rel="noopener noreferrer external" target="_blank" href="https://github.com/immunefi-team/Web3-Security-Library#vulnerabilities">Immunefi Vulnerability Library</a></li> </ul> <p><strong>QuillHash collections</strong></p> <ul> <li><a rel="noopener noreferrer external" target="_blank" href="https://github.com/Quillhash/DeFi-Attack-Vectors">DeFi Attack Vectors</a></li> <li><a rel="noopener noreferrer external" target="_blank" href="https://github.com/Quillhash/Solidity-Attack-Vectors">Solidity Attack Vectors</a></li> </ul> <p><strong>Additional references</strong></p> <ul> <li><a rel="noopener noreferrer external" target="_blank" href="https://github.com/shanzson/Smart-Contract-Auditor-Tools-and-Techniques?tab=readme-ov-file#defi-focused-security-resources">DeFi-Focused Security Resources</a></li> <li><a rel="noopener noreferrer external" target="_blank" href="https://github.com/0xJuancito/multichain-auditor">Multichain Auditor: Cross-Chain Vulnerabilities and Checklist</a></li> </ul> <h2 id="audit-reports">Audit Reports</h2> <p>Reading past audit reports is one of the most effective ways to develop an eye for bugs. You see how real auditors reason, what they flag, and how they write findings.</p> <p><strong>Contest platforms</strong></p> <ul> <li><a rel="noopener noreferrer external" target="_blank" href="https://code4rena.com/reports">Code4rena Reports</a></li> <li><a rel="noopener noreferrer external" target="_blank" href="https://github.com/sherlock-protocol/sherlock-reports">Sherlock Reports</a></li> <li><a rel="noopener noreferrer external" target="_blank" href="https://theauditorbook.com/">The Auditor Book</a> — aggregated Sherlock and Code4rena findings</li> <li><a rel="noopener noreferrer external" target="_blank" href="https://audit-hero.com/search-findings">Audit Hero</a> — search Code4rena and Sherlock findings together</li> <li><a rel="noopener noreferrer external" target="_blank" href="https://solodit.cyfrin.io/?i=HIGH%2CMEDIUM">Solodit by Cyfrin</a> — filtered view of high and medium findings across contests</li> </ul> <p><strong>Bug bounty writeups</strong></p> <ul> <li><a rel="noopener noreferrer external" target="_blank" href="https://github.com/sayan011/Immunefi-bug-bounty-writeups-list">Immunefi Bug Bounty Writeups</a></li> </ul> <p><strong>Security firms</strong></p> <ul> <li><a rel="noopener noreferrer external" target="_blank" href="https://consensys.io/diligence/audits/">Consensys Diligence</a></li> <li><a rel="noopener noreferrer external" target="_blank" href="https://github.com/trailofbits/publications#ethereumevm">Trail of Bits (Ethereum/EVM)</a></li> <li><a rel="noopener noreferrer external" target="_blank" href="https://blog.openzeppelin.com/tag/security-audits">OpenZeppelin Security Audits</a></li> <li><a rel="noopener noreferrer external" target="_blank" href="https://github.com/spearbit/portfolio">Spearbit Portfolio</a></li> <li><a rel="noopener noreferrer external" target="_blank" href="https://github.com/Quillhash/QuillAudit_Reports">QuillHash Audit Reports</a></li> </ul> <p><strong>Solo auditor portfolios</strong></p> <p>These are worth reading to see how individual auditors present their work:</p> <ul> <li><a rel="noopener noreferrer external" target="_blank" href="https://github.com/nullity00/zk-security-reviews">nullity00 (ZK security reviews)</a></li> <li><a rel="noopener noreferrer external" target="_blank" href="https://github.com/nevillehuang/Portfolio">NevilleHuang</a></li> <li><a rel="noopener noreferrer external" target="_blank" href="https://github.com/zobront/audits">Zobront Audits</a></li> </ul> <p><strong>Lists and directories</strong></p> <ul> <li><a rel="noopener noreferrer external" target="_blank" href="https://github.com/0xNazgul/Blockchain-Security-Audit-List">Blockchain Security Audit List</a> — firms and solo auditors</li> <li><a rel="noopener noreferrer external" target="_blank" href="https://gist.github.com/cwhinfrey/9fd1bbc31bbcff08fca242b90c7f875d">Bridge Hack List</a></li> </ul> <h3 id="secureum-safu-series">Secureum SAFU Series</h3> <p>A focused set of posts analyzing the security of specific DeFi protocols:</p> <ul> <li><a rel="noopener noreferrer external" target="_blank" href="https://secureum.substack.com/p/eth2-security-overview-secureum-1">Eth2 Security Overview</a></li> <li><a rel="noopener noreferrer external" target="_blank" href="https://secureum.substack.com/p/smart-contract-security-resources">Smart Contract Security Resources</a></li> <li><a rel="noopener noreferrer external" target="_blank" href="https://secureum.substack.com/p/making-defi-safu-secureum-3">Making DeFi SAFU</a></li> <li><a rel="noopener noreferrer external" target="_blank" href="https://secureum.substack.com/p/making-hermez-safu-secureum-4">Making Hermez SAFU</a></li> <li><a rel="noopener noreferrer external" target="_blank" href="https://secureum.substack.com/p/making-cover-safu-secureum-5">Making Cover SAFU</a></li> <li><a rel="noopener noreferrer external" target="_blank" href="https://secureum.substack.com/p/smart-contract-security-101-secureum">Making Opyn SAFU</a></li> <li><a rel="noopener noreferrer external" target="_blank" href="https://secureum.substack.com/p/making-defi-safu-secureum-3">Smart Contract Security 101</a></li> <li><a rel="noopener noreferrer external" target="_blank" href="https://secureum.substack.com/p/making-primitive-safu-secureum-8">Making Primitive SAFU</a></li> <li><a rel="noopener noreferrer external" target="_blank" href="https://secureum.substack.com/p/making-alpha-safu-secureum-9">Making Alpha SAFU</a></li> </ul> <h2 id="ctfs-and-hands-on-practice">CTFs and Hands-On Practice</h2> <p>Reading about vulnerabilities is not enough. You need to exploit them yourself. These CTFs give you practice in a structured environment.</p> <ul> <li><a rel="noopener noreferrer external" target="_blank" href="https://ethernaut.openzeppelin.com/">Ethernaut</a> — the classic starting point for smart contract security challenges</li> <li><a rel="noopener noreferrer external" target="_blank" href="https://capturetheether.com/">Capture the Ether</a></li> <li><a rel="noopener noreferrer external" target="_blank" href="https://www.damnvulnerabledefi.xyz/">Damn Vulnerable DeFi</a> — DeFi-specific challenges, progressively harder</li> <li><a rel="noopener noreferrer external" target="_blank" href="https://ctf.paradigm.xyz/">Paradigm CTF</a></li> </ul> <blockquote class="markdown-alert-tip"> <p>After completing a challenge, read other players' writeups. The same vulnerability can often be exploited in multiple ways, and seeing different approaches sharpens your thinking.</p> </blockquote> <h2 id="contest-practice">Contest Practice</h2> <p>Once you have finished the CTFs, first-flight contests are a low-stakes way to practice writing findings on real (if simpler) codebases.</p> <ul> <li><a rel="noopener noreferrer external" target="_blank" href="https://codehawks.cyfrin.io/first-flights?ended=true&amp;judging=true&amp;live=true&amp;sort=endDate&amp;upcoming=true">CodeHawks First Flights</a></li> </ul> <h2 id="writing-proof-of-concept-exploits">Writing Proof of Concept Exploits</h2> <p>A finding without a working PoC is weak. These resources cover how to build them properly.</p> <ul> <li><a rel="noopener noreferrer external" target="_blank" href="https://github.com/immunefi-team/Web3-Security-Library/blob/main/Check%20This%20Out/README.md#poc-like-a-pro">PoC Like a Pro</a></li> <li><a rel="noopener noreferrer external" target="_blank" href="https://github.com/shanzson/Smart-Contract-Auditor-Tools-and-Techniques?tab=readme-ov-file#pocs">Coinspect and DeFi Hack Labs PoCs</a></li> </ul> <h2 id="postmortems-and-bug-fix-analysis">Postmortems and Bug Fix Analysis</h2> <p>Studying how protocols responded to real exploits teaches you what auditors missed and why. This is underrated as a learning method.</p> <ul> <li><a rel="noopener noreferrer external" target="_blank" href="https://github.com/razzorsec/AuditorsRoadmap?tab=readme-ov-file#13-postmortems--bugfixes">Postmortem Writeups</a></li> <li><a rel="noopener noreferrer external" target="_blank" href="https://github.com/sirhashalot/SCV-List?tab=readme-ov-file">SCV-List</a></li> </ul> <h2 id="where-to-start">Where to Start</h2> <p>If you are new to smart contract security, a reasonable progression is:</p> <ol> <li>Learn Solidity basics using Solidity by Example and the Secureum 101 posts</li> <li>Understand the EVM at a basic level before going deeper</li> <li>Work through Ethernaut, then Damn Vulnerable DeFi</li> <li>Read 10 to 20 high-severity findings on Solodit and understand each one</li> <li>Participate in a CodeHawks First Flight contest</li> <li>Expand your DeFi knowledge in parallel with your security knowledge</li> </ol> <p>The two skills reinforce each other. The better you understand how a protocol is supposed to work, the easier it is to see where it breaks.</p> 2025-01-01T00:00:00+00:00 2025-01-01T00:00:00+00:00 Unknown https://akash11.com/email/ 2025-01-01T00:00:00+00:00 2025-01-01T00:00:00+00:00 Unknown https://akash11.com/github/ 2025-01-01T00:00:00+00:00 2025-01-01T00:00:00+00:00 Unknown https://akash11.com/linkedin/ 2025-01-01T00:00:00+00:00 2025-01-01T00:00:00+00:00 Unknown https://akash11.com/resume/ 2025-01-01T00:00:00+00:00 2025-01-01T00:00:00+00:00 Unknown https://akash11.com/telegram/ 2025-01-01T00:00:00+00:00 2025-01-01T00:00:00+00:00 Unknown https://akash11.com/x/ 2023-01-08T00:00:00+00:00 2025-05-28T00:00:00+00:00 Unknown https://akash11.com/about/ <p>I'm Akash Vaghela, a full-stack engineer based in Jamnagar, Gujarat.</p> <p>I started with a Chemical Engineering degree, a strong academic record, and a final-year project that received funding from the Gujarat government's Student Startup and Innovation Policy (SSIP). But I realized early that it wasn't the direction I wanted my career to go. So I trusted that instinct, switched paths after graduation, and joined Masai School to learn software development.</p> <p>That decision led to five years of building things across startups and enterprises. I started at Capgemini, working with a global team on internal tools for P&amp;G. Then came a run of startup roles, founding engineer stints, zero-to-one builds, direct customer interaction, each one pushing me into unfamiliar territory and making me a better engineer for it. Along the way I've tripled product activation rates with AI-powered onboarding, shipped real-time WebSocket dashboards, and independently launched two monetized products that are live today.</p> <p>Most of that work has been in the MERN stack. But I'm now deliberately expanding into Rust and the Solana ecosystem. It's early days. I'm learning, getting involved in communities, and building toward a longer-term interest in systems programming and on-chain development. The transition feels right, for the same reason the original career switch did.</p> <p>Outside of work, I read a lot. Tech, fiction, philosophy, no particular loyalty to genre. A few books that have genuinely shaped how I think: <strong><em>Siddhartha</em></strong> by Hermann Hesse, <strong><em>Tuesdays with Morrie</em></strong> by Mitch Albom, and <strong><em>Animal Farm</em></strong> by George Orwell. I also watch a lot of films, particularly science fiction, and find myself paying attention to the craft, the shot selection, the sound design, how a story is constructed.</p> <p>Feel free to reach out on <a href="/linkedin">LinkedIn</a> or <a href="/x">X</a>.</p> 2023-01-08T00:00:00+00:00 2023-01-08T00:00:00+00:00 Unknown https://akash11.com/certifications/ <table><thead><tr><th>Certification</th><th>Issuer</th><th>Year</th></tr></thead><tbody> <tr><td><a rel="noopener noreferrer external" target="_blank" href="https://www.coursera.org/account/accomplishments/specialization/certificate/5VFF9SE3B5GC">Blockchain Specialization</a></td><td>University at Buffalo</td><td>2022</td></tr> <tr><td><a rel="noopener noreferrer external" target="_blank" href="https://www.coursera.org/account/accomplishments/certificate/5V6TT9R9R9VD">Decentralized Applications (Dapps)</a></td><td>University at Buffalo</td><td>2022</td></tr> <tr><td><a rel="noopener noreferrer external" target="_blank" href="https://www.coursera.org/account/accomplishments/certificate/D5YAQW93HZVJ">Blockchain Platforms</a></td><td>University at Buffalo</td><td>2022</td></tr> <tr><td><a rel="noopener noreferrer external" target="_blank" href="https://www.coursera.org/account/accomplishments/certificate/QZTE4GTVAR7E">Smart Contracts</a></td><td>University at Buffalo</td><td>2022</td></tr> <tr><td><a rel="noopener noreferrer external" target="_blank" href="https://www.coursera.org/account/accomplishments/certificate/5F88UB8MMKUF">Blockchain Basics</a></td><td>University at Buffalo</td><td>2022</td></tr> <tr><td><a rel="noopener noreferrer external" target="_blank" href="https://www.udemy.com/certificate/UC-a18dbb93-6296-41a7-87fc-5d7625ff9a93/">Modern JavaScript for React JS - ES6</a></td><td>Udemy</td><td>2022</td></tr> <tr><td><a rel="noopener noreferrer external" target="_blank" href="https://codedamn.com/certificate/verify/a8278102913e250a5aca570d1a0e755382788f54">CI/CD With GitHub Actions</a></td><td>Codedamn</td><td>2022</td></tr> <tr><td><a rel="noopener noreferrer external" target="_blank" href="https://www.coursera.org/account/accomplishments/certificate/9EN2UE5V9PJK">Version Control with Git</a></td><td>Atlassian University</td><td>2022</td></tr> <tr><td><a rel="noopener noreferrer external" target="_blank" href="https://www.udemy.com/certificate/UC-d67a13cb-354c-406e-8ea3-a6f1072917bf/">Git and GitHub from scratch</a></td><td>Udemy</td><td>2022</td></tr> <tr><td><a rel="noopener noreferrer external" target="_blank" href="https://www.credly.com/badges/f3c42bd4-2320-42b3-b7ad-52b02a29e087">AWS Certified Developer – Associate</a></td><td>Amazon Web Services</td><td>2021</td></tr> <tr><td><a rel="noopener noreferrer external" target="_blank" href="https://www.coursera.org/account/accomplishments/specialization/certificate/XAL89RHX2A58">Cloud Application Development Foundations</a></td><td>IBM</td><td>2021</td></tr> <tr><td><a rel="noopener noreferrer external" target="_blank" href="https://www.credly.com/badges/c8e6e53d-fc1a-4c2a-a27f-ec4779e24015">Developing Cloud Apps with Node.js and React</a></td><td>IBM</td><td>2021</td></tr> <tr><td><a rel="noopener noreferrer external" target="_blank" href="https://www.credly.com/badges/0e4a51cc-75f1-480a-b82d-11bf95207bd0">Developing Cloud Native Applications</a></td><td>IBM</td><td>2021</td></tr> <tr><td><a rel="noopener noreferrer external" target="_blank" href="https://www.credly.com/badges/f31760e4-4bcb-4779-838f-acd4954c3e7c">Web Development with HTML, CSS, JavaScript Essentials</a></td><td>IBM</td><td>2021</td></tr> <tr><td><a rel="noopener noreferrer external" target="_blank" href="https://www.credly.com/badges/d5ffc5f6-4402-48fe-87cc-8ff1bf0bbccf">Introduction to Cloud Computing</a></td><td>IBM</td><td>2021</td></tr> <tr><td><a rel="noopener noreferrer external" target="_blank" href="https://www.coursera.org/account/accomplishments/certificate/ANYBFGN4235L">Agile Software Development</a></td><td>University of Minnesota</td><td>2021</td></tr> <tr><td><a rel="noopener noreferrer external" target="_blank" href="https://www.udemy.com/certificate/UC-767bbec9-4033-4a30-9afd-3297faaa7e2d/">JavaScript - Basics to Advanced</a></td><td>Udemy</td><td>2021</td></tr> </tbody></table> 2023-01-08T00:00:00+00:00 2025-05-28T00:00:00+00:00 Unknown https://akash11.com/work/ <h2 id="independent-developer">Independent Developer</h2> <p><strong>Full Stack Engineer</strong> · Mar 2025 – Present · Ahmedabad, India</p> <p>Building and shipping my own products.</p> <ul> <li><strong><a rel="noopener noreferrer external" target="_blank" href="https://viralvision.akash11.com">ViralVision</a></strong> — AI image platform for thumbnail generation, upscaling, and character-consistent editing. Integrated the Nano Banana 2 API, built JWT auth and a credit billing system from scratch.</li> <li><strong><a rel="noopener noreferrer external" target="_blank" href="https://chromewebstore.google.com/detail/contentcurator/cohcdmigcodfchfbjaangdfnlnfkkeim">ContentCurator</a></strong> — Chrome extension for YouTube analytics. Features channel and video tracking, bookmarks, group management, CSV export, and MongoDB-backed cloud sync.</li> </ul> <hr /> <h2 id="indecab"><a rel="noopener noreferrer external" target="_blank" href="https://indecab.com">Indecab</a></h2> <p><strong>Full Stack Engineer</strong> · Jun 2024 – Mar 2025 · Mumbai, India (Remote)</p> <ul> <li>Reduced legacy code issues by 40% by migrating multiple Meteor modules to the latest version, improving reliability and cutting new developer onboarding time.</li> <li>Built a Help Center CMS with modular React components, replacing ad-hoc documentation and giving the support team a proper content management workflow.</li> <li>Handled Sentry error investigations, implemented bug fixes, and improved error handling across the codebase.</li> </ul> <hr /> <h2 id="visilean"><a rel="noopener noreferrer external" target="_blank" href="https://visilean.com">Visilean</a></h2> <p><strong>UI Developer</strong> · Feb 2024 – May 2024 · Ahmedabad, India (Hybrid)</p> <ul> <li>Revamped the Takt Visualizer dashboard for full responsiveness across desktop, tablet, and mobile, improving usability for field-based construction planning teams.</li> <li>Integrated WebSocket-based real-time data updates, increasing dashboard refresh efficiency by 50%.</li> <li>Optimized API and WebSocket responses to improve page speed and navigation.</li> </ul> <hr /> <h2 id="salesrobot"><a rel="noopener noreferrer external" target="_blank" href="https://salesrobot.co">SalesRobot</a></h2> <p><strong>Full Stack Engineer</strong> · Sep 2022 – Jan 2024 · New Delhi, India (Remote)</p> <ul> <li>Built SalesGPT, an AI-powered onboarding chatbot that tripled product activation rates from 11% to 35% by guiding new users through core features contextually.</li> <li>Reduced time-to-feature access by 60% by redesigning key user flows and consolidating high-usage tools into a unified interface.</li> <li>Developed the LeadZilla Chrome extension UI and integrated credit usage features.</li> <li>Used OpenAI APIs to generate LinkedIn posts, comments, and icebreaker lines for outbound automation.</li> </ul> <hr /> <h2 id="capgemini"><a rel="noopener noreferrer external" target="_blank" href="https://capgemini.com">Capgemini</a></h2> <p><strong>Software Engineer</strong> · Jun 2021 – Sep 2022 · Bangalore, India (Hybrid)</p> <ul> <li>Built a reusable React component library (calendar, tooltips, map markers) for P&amp;G's internal enterprise tools, adopted across multiple modules.</li> <li>Migrated the FullCalendar library to the latest version and integrated Google Maps with React for product location tracking.</li> <li>Delivered data visualization and workflow enhancements in direct collaboration with P&amp;G's internal stakeholders.</li> </ul>