+- Sick Gaming (https://www.sickgaming.net)
+-- Forum: Programming (https://www.sickgaming.net/forum-76.html)
+--- Forum: Python (https://www.sickgaming.net/forum-83.html)
+--- Thread: [Tut] Solidity File Layout – SPDX License ID and Version Pragmas (/thread-99973.html)
[Tut] Solidity File Layout – SPDX License ID and Version Pragmas - xSicKxBot - 09-22-2022
Solidity File Layout – SPDX License ID and Version Pragmas
<div>
<div class="kk-star-ratings kksr-auto kksr-align-left kksr-valign-top" data-payload="{"align":"left","id":"703612","slug":"default","valign":"top","ignore":"","reference":"auto","class":"","count":"1","readonly":"","score":"5","best":"5","gap":"5","greet":"Rate this post","legend":"5\/5 - (1 vote)","size":"24","width":"142.5","_legend":"{score}\/{best} - ({count} {votes})","font_factor":"1.25"}">
<div class="kksr-stars">
<div class="kksr-stars-inactive">
<div class="kksr-star" data-star="1" style="padding-right: 5px">
<div class="kksr-icon" style="width: 24px; height: 24px;"></div>
</p></div>
<div class="kksr-star" data-star="2" style="padding-right: 5px">
<div class="kksr-icon" style="width: 24px; height: 24px;"></div>
</p></div>
<div class="kksr-star" data-star="3" style="padding-right: 5px">
<div class="kksr-icon" style="width: 24px; height: 24px;"></div>
</p></div>
<div class="kksr-star" data-star="4" style="padding-right: 5px">
<div class="kksr-icon" style="width: 24px; height: 24px;"></div>
</p></div>
<div class="kksr-star" data-star="5" style="padding-right: 5px">
<div class="kksr-icon" style="width: 24px; height: 24px;"></div>
</p></div>
</p></div>
<div class="kksr-stars-active" style="width: 142.5px;">
<div class="kksr-star" style="padding-right: 5px">
<div class="kksr-icon" style="width: 24px; height: 24px;"></div>
</p></div>
<div class="kksr-star" style="padding-right: 5px">
<div class="kksr-icon" style="width: 24px; height: 24px;"></div>
</p></div>
<div class="kksr-star" style="padding-right: 5px">
<div class="kksr-icon" style="width: 24px; height: 24px;"></div>
</p></div>
<div class="kksr-star" style="padding-right: 5px">
<div class="kksr-icon" style="width: 24px; height: 24px;"></div>
</p></div>
<div class="kksr-star" style="padding-right: 5px">
<div class="kksr-icon" style="width: 24px; height: 24px;"></div>
</p></div>
</p></div>
</div>
<div class="kksr-legend" style="font-size: 19.2px;"> 5/5 – (1 vote) </div>
</div>
<figure class="wp-block-embed-youtube wp-block-embed is-type-video is-provider-youtube"><a href="https://blog.finxter.com/layout-of-a-solidity-source-file-spdx-license-identifier-and-version-pragmas/"><img src="https://blog.finxter.com/wp-content/plugins/wp-youtube-lyte/lyteCache.php?origThumbUrl=https%3A%2F%2Fi.ytimg.com%2Fvi%2FkuFtZbCzRnM%2Fhqdefault.jpg" alt="YouTube Video"></a><figcaption></figcaption></figure>
<p>In the <a rel="noreferrer noopener" href="https://blog.finxter.com/top-solidity-smart-contract-examples-for-learning/" data-type="post" data-id="663675" target="_blank">previous articles</a>, we looked at some of the representative examples of smart contracts representing possible real-world scenarios. </p>
<p>Our main focus was on capturing the essence of each case, without particular attention given to the general structure, i.e. layout of the respective source files. </p>
<p>However, in this mini-series starting with this article, we will focus particularly on the <a href="https://blog.finxter.com/layout-of-a-solidity-source-file/" data-type="post" data-id="455693" target="_blank" rel="noreferrer noopener">source file layout</a>. </p>
<div class="wp-block-file"><object class="wp-block-file__embed" data="https://blog.finxter.com/wp-content/uploads/2022/09/Solidity-Blog-Part-16.pdf" type="application/pdf" style="width:100%;height:600px" aria-label="Embed of Solidity File Layout."></object><a id="wp-block-file--media-d6960f3d-5d83-4e98-ab44-fcadd98b5f45" href="https://blog.finxter.com/wp-content/uploads/2022/09/Solidity-Blog-Part-16.pdf">Solidity File Layout</a><a href="https://blog.finxter.com/wp-content/uploads/2022/09/Solidity-Blog-Part-16.pdf" class="wp-block-file__button" download aria-describedby="wp-block-file--media-d6960f3d-5d83-4e98-ab44-fcadd98b5f45">Download</a></div>
<p class="has-base-background-color has-background"><em>The articles will continue with our tradition of going hand in hand with the official Solidity documentation, with the particular topic of our current interest available <a href="https://docs.soliditylang.org/en/v0.8.15/layout-of-source-files.html" data-type="URL" data-id="https://docs.soliditylang.org/en/v0.8.15/layout-of-source-files.html" target="_blank" rel="noreferrer noopener">here</a>.</em></p>
<p><strong>Info</strong>: As we’ve reached such a nice, round number of <a href="https://blog.finxter.com/solidity-crash-course/" data-type="post" data-id="445146" target="_blank" rel="noreferrer noopener">articles on Solidity</a>, I have a small foreword for my faithful audience. </p>
<p>For those of us who missed or skipped previous articles, the intent behind the content is to supplement and clarify the original documentation and even present it in a style that I find to be more appropriate to us as the audience. </p>
<p>Given that we come from various backgrounds, some less and some more technical, it is my permanent goal to soften the material and make it as close as possible to each reader. Sometimes, completely unannounced and unprovoked, I’ll even try and sprinkle some humor onto the content. </p>
<p>Will I succeed in making it funny and engaging? That’s whole another story <img src="https://s.w.org/images/core/emoji/14.0.0/72x72/1f642.png" alt="?" class="wp-smiley" style="height: 1em; max-height: 1em;" /></p>
<h2><a></a>SPDX License Identifier</h2>
<p>Smart contracts are somewhat a mystery to unfamiliar folks, and a mystery usually implies a certain amount of distrust. Even so, the more sensitive the subject is, the greater the amount of distrust. The best way to turn distrust into trust is to make the content in question open and available. </p>
<p>When we’re talking about <a href="https://blog.finxter.com/introduction-to-smart-contracts-and-solidity-part-3-blockchain-basics/" data-type="post" data-id="537705" target="_blank" rel="noreferrer noopener">smart contracts</a>, the openness of a smart contract means the availability of its source code. However, making the source code available frequently triggers legal problems regarding copyright. </p>
<p>To alleviate these problems, the Solidity compiler instigates the use of <em><strong>SPDX license identifiers</strong></em>.</p>
<p class="has-global-color-8-background-color has-background"><img src="https://s.w.org/images/core/emoji/14.0.0/72x72/2139.png" alt="ℹ" class="wp-smiley" style="height: 1em; max-height: 1em;" /> <strong>Info</strong>: <a href="https://spdx.dev/" data-type="URL" data-id="https://spdx.dev/" target="_blank" rel="noreferrer noopener">SPDX</a> stands for the <strong><em>Software Package Data Exchange</em></strong>, which is “<em>An open standard for communicating software bill of material information, including components, licenses, copyrights, and security references. SPDX reduces redundant work by providing a common format for companies and communities to share important data, thereby streamlining and improving compliance.</em>“</p>
<p>Yes, I agree, it’s a lengthy sentence, but the main takeaway ideas are <em>a communication standard</em>, <em>an instrument of compliance</em>, and <em>a data exchange format</em>:</p>
<ol type="1">
<li>SPDX is a standard used for communicating the information about the software contents;</li>
<li>SPDX reduces redundant work and improves compliance;</li>
<li>SPDX provides a common format for data sharing between companies and communities;</li>
</ol>
<p>An SPDX license identifier should be included at the beginning of the source file, e.g.</p>
<pre class="EnlighterJSRAW" data-enlighter-language="generic" data-enlighter-theme="" data-enlighter-highlight="" data-enlighter-linenumbers="" data-enlighter-lineoffset="" data-enlighter-title="" data-enlighter-group="">// SPDX-License-Identifier: GPL-3.0-or-later</pre>
<p>Although SPDX license identifiers are machine-readable, the compiler does not check if the license part of the comment is in the list of licenses allowed by <a href="https://spdx.org/licenses/" data-type="URL" data-id="https://spdx.org/licenses/" target="_blank" rel="noreferrer noopener">SPDX</a>. </p>
<p>Instead, the compiler will just include the string in the bytecode <em><a rel="noreferrer noopener" href="https://docs.soliditylang.org/en/v0.8.15/metadata.html#metadata" data-type="URL" data-id="https://docs.soliditylang.org/en/v0.8.15/metadata.html#metadata" target="_blank">metadata</a></em>. </p>
<p>We will touch on the subject of contract metadata in future articles, but until then, let’s just remember that there is a thing called metadata.</p>
<p class="has-global-color-8-background-color has-background"><strong><img src="https://s.w.org/images/core/emoji/14.0.0/72x72/2139.png" alt="ℹ" class="wp-smiley" style="height: 1em; max-height: 1em;" /> Info</strong>: Metadata can be loosely defined as <em>“data/information about data”</em>, meaning it provides more information or description of certain data.</p>
<p>We don’t have to specify a license or if the case is that the source code is <em>closed-source</em> (opposite of open-source), the recommendation is that we use a special value UNLICENSED. </p>
<p>The UNLICENSED value implies that usage is not allowed, i.e. there is not a corresponding item in SPDX license list; it differs from the value UNLICENSE which grants all rights to everyone. </p>
<p><a rel="noreferrer noopener" href="https://docs.npmjs.com/cli/v7/configuring-npm/package-json#license" data-type="URL" data-id="https://docs.npmjs.com/cli/v7/configuring-npm/package-json#license" target="_blank">Solidity documentation</a> authors note that Solidity adheres to the npm recommendation.</p>
<p>If we as developers supply the UNLICENSE comment, we are still tied by the obligation related to licensing, i.e. we have to mention a specific license header or the original copyright holder in the source files.</p>
<p>Although the compiler recognizes the comment placed at any location in the source file, the recommendation, and good practice is to put it at the top of the file.</p>
<h2><a></a>Pragmas</h2>
<p>We’ve mentioned the <code>pragma</code> keyword <a href="https://blog.finxter.com/solidity-by-example-understanding-modular-contracts/" data-type="post" data-id="692480" target="_blank" rel="noreferrer noopener">somewhere</a> in the first few articles, but now we’ll use the opportunity to say a few more words about it.</p>
<p>Pragma keyword is the element of the Solidity programming language that enables specific <a href="https://blog.finxter.com/how-to-install-the-solidity-compiler-with-npm/" data-type="post" data-id="606118" target="_blank" rel="noreferrer noopener">Solidity compiler</a> (remember <code>solc</code>) features or validations, i.e. checks. </p>
<p>As the <code>pragma</code> keyword scope is its source file, we’d have to add the pragma to all our files to enable it in our whole project.</p>
<p class="has-global-color-8-background-color has-background"><img src="https://s.w.org/images/core/emoji/14.0.0/72x72/1f4a1.png" alt="?" class="wp-smiley" style="height: 1em; max-height: 1em;" /> <strong>Note</strong>: A pragma from an imported file does not apply to the importer file, i.e. the file that imports the imported file.</p>
<h3><a></a>Version Pragma</h3>
<p>We always use a version pragma for limiting the source file(s) compilation to a specific range of compiler versions. </p>
<p>The intention behind this step is the prevention of incompatible changes introduced with future versions of compilers. </p>
<p>According to the Solidity authors, occurrences of incompatible changes are reduced to an absolute minimum, meaning that in all other cases i.e. cases of compatible changes, the changes in <a href="https://blog.finxter.com/solidity/" data-type="post" data-id="37379" target="_blank" rel="noreferrer noopener">Solidity language semantics</a> visibly coincide with the changes in language syntax. </p>
<p>To stay on the safe side, the recommendation is to study the changelog at least for releases that carry breaking changes, marked <code>x.0.0</code> (major releases) or <code>0.x.0</code> (minor releases).</p>
<p class="has-base-background-color has-background"><img src="https://s.w.org/images/core/emoji/14.0.0/72x72/2139.png" alt="ℹ" class="wp-smiley" style="height: 1em; max-height: 1em;" /> <strong>Info</strong>: semantic is relating to meaning in language or logic.</p>
<p>As in every our example so far, we’re using the version pragma as:</p>
<p class="has-global-color-8-background-color has-background"><strong>Note</strong>: <code>pragma solidity ^0.x.y;</code> allows changes that do not modify the left-most <strong>non-zero</strong> digit in the [major, minor, patch] tuple (<em><a href="https://docs.npmjs.com/cli/v6/using-npm/semver#caret-ranges-123-025-004">docs</a></em>).</p>
<p>The following line instructs the compilation process to use a compiler with the lowest version of 0.5.2 and with the highest version not exceeding 0.6.0 (this condition is incorporated by a <code>^</code> symbol):</p>
<pre class="EnlighterJSRAW" data-enlighter-language="generic" data-enlighter-theme="" data-enlighter-highlight="" data-enlighter-linenumbers="" data-enlighter-lineoffset="" data-enlighter-title="" data-enlighter-group="">pragma solidity ^0.5.2;</pre>
<p>By recalling the article about semantic versioning, we’ll remember that no breaking changes are introduced until a minor version of <code>0.6.0</code> (in this specific case), therefore we can be sure that our code will compile just as we expect it to. </p>
<p>Also, by using the line above, we didn’t lock on the specific version, so the last part of the version label, i.e. the patch number can increase, leaving enough space for the compiler bug fixes. </p>
<p>Besides this most common way of expressing the allowed versions of the compiler, even more, complex rules are available by using the syntax available <a rel="noreferrer noopener" href="https://docs.npmjs.com/cli/v6/using-npm/semver" data-type="URL" data-id="https://docs.npmjs.com/cli/v6/using-npm/semver" target="_blank">here</a>.</p>
<p class="has-global-color-8-background-color has-background"><img src="https://s.w.org/images/core/emoji/14.0.0/72x72/1f4a1.png" alt="?" class="wp-smiley" style="height: 1em; max-height: 1em;" /> <strong>Note</strong>: <code>version pragma</code> just instructs the compiler to self-check if it is compliant with the version required by the source file. In case of a mismatch, the compiler will throw an (in)appropriate error. I mean, who ever saw an appropriate error, anyways?</p>
<h2><a></a>Conclusion</h2>
<p>With this introductory article to the topic of the layout of a Solidity source file, we covered a few very light concepts, including SPDX license identifier, reintroduced the pragma keyword, and retouched the version pragma. </p>
<p>In the next article, we will continue with the next two pragmas and other, very interesting topics.</p>
<p>In the SPDX License Identifier section, we were asking around inconspicuously about the SPDX. We wanted to find out what it is, how and when it is used, and how it can make our developing life easier.</p>
<p>In the Pragmas section, we proudly reminded ourselves of the knowledge from long ago, why do we have to slam a pragma at the beginning of each source file? </p>
<p>If at least they looked nice… Starting our coding masterpieces with a dangling comment seemed like a skewed joke (like most of mine do) – until we learned why <img src="https://s.w.org/images/core/emoji/14.0.0/72x72/1f642.png" alt="?" class="wp-smiley" style="height: 1em; max-height: 1em;" /></p>
<hr class="wp-block-separator has-alpha-channel-opacity"/>
</div>
https://www.sickgaming.net/blog/2022/09/21/solidity-file-layout-spdx-license-id-and-version-pragmas/