Solidity Scoping – A Helpful Guide with Video

As promised in the previous article, we’ll get more closely familiar with the concept of scoping next. We’ll explain what scoping is, why it exists, and how it helps us in programming.

It’s part of our long-standing tradition to make this (and other) articles a faithful companion, or a supplement to the official Solidity documentation.

Scopes Overview

Scope refers to the context in which we can access a defined variable or a function. There are three main types of scope specific to Solidity:

• global,
• contract, and
• function scope.

In the global scope, variables, and functions are defined at the global level, i.e., outside of any contract or function, and we can access them from any place in the source code.

In the contract scope, variables and functions are defined within a contract, but outside of any function, so we can access them from anywhere within the specific contract. However, these variables and functions are inaccessible from outside the contract scope.

In the function scope, variables and functions are defined within a function and we can access them exclusively from inside that function.

💡 Note:

The concept of scopes in Solidity is similar and based on the concept of scopes in the C99 programming language. In both languages, a “scope” refers to the context in which a variable or function is defined and can be accessed.

In C99 (a C language standard from 1999), variables and functions can be defined at either the global level (i.e., outside of any function) or within a function. There is no “contract” scope in C99.

Global Scope

Let’s take a look at a simple example of the global scope:

pragma solidity ^0.6.12;

uint public globalCounter;

function incrementGlobalCounter() public {
    globalCounter++;
}

In this example, the globalCounter variable is defined at the global level and is, therefore, in the global scope. We can access it from anywhere in the code, including from within the incrementGlobalCounter(...) function.

✅ Reminder: Global variables and functions can be accessed and modified by any contract or function that has access to them. We can find this behavior useful for sharing data across contracts or functions, but it can also present security risks if the global variables or functions are not properly protected.

Contract Scope

As explained above, variables and functions defined within a contract (but outside of any function) are in contract scope, and we can access them from anywhere within the contract.

Contract-level variables and functions are useful for storing and manipulating data that is specific to a particular contract and is not meant to be shared with other contracts or functions.

Let’s take a look at a simple example of the contract scope:

pragma solidity ^0.6.12;

contract Counter {
    uint public contractCounter;

    function incrementContractCounter() public {
        contractCounter++;
    }
}

In this example, the contractCounter variable is defined within the Counter contract and is, therefore, in contract scope. It is available for access from anywhere within the Counter contract, including from within the incrementContractCounter() function.

⚡ Warning: We should be aware that contract-level variables and functions are only accessible from within the contract in which they are defined. They cannot be accessed from other contracts or from external accounts.

Function Scope

Variables and functions that are defined within a function are in the function scope and can only be accessed from within that function.

Function-level variables and functions are useful for storing and manipulating data that is specific to a particular function and is not meant to be shared with other functions or with the contract as a whole.

Let’s take a look at the following example of the function scope:

pragma solidity ^0.6.12;

contract Counter {
    function incrementCounter(uint incrementAmount) public {
        uint functionCounter = 0;
        functionCounter += incrementAmount;
    }
}

In this example, the functionCounter variable is defined within the incrementCounter(...) function and is, therefore, in the function scope. It can only be accessed from within the incrementCounter function and is not accessible from other functions or from outside the contract.

C99 Scoping Rules

Now, let’s take a look at an interesting example showing minimal scoping by using curly braces:

// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.5.0 <0.9.0;
contract C {
    function minimalScoping() pure public {
        {
            uint same;
            same = 1;
        }

        {
            uint same;
            same = 3;
        }
    }
}

Each of the curly braces pair forms a distinct scope, containing a declaration and initialization of the variable same.

This example will compile without warnings or errors because each of the variable’s lifecycles is contained in its own disjoint scope, and there is no overlap between the two scopes.

Shadowing

In some special cases, such as this one demonstrating C99 scoping rules below, we’d come across a phenomenon called shadowing.

💡 Shadowing means that two or more variables share their name and have intersected scopes, with the first one as the outer scope and the second one as the inner scope.

Let’s take a closer look to get a better idea of what’s all about:

// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.5.0 <0.9.0;
// This will report a warning
contract C {
    function f() pure public returns (uint) {
        uint x = 1;
        {
            x = 2; // this will assign to the outer variable
            uint x;
        }
        return x; // x has value 2
    }
}

There are two variables called x; the first one is in the outer scope, and the second one is in the inner scope.

The inner scope is contained in or surrounded by the outer scope.

Therefore, the first and the second assignment assign the value 1, and then value 2 to the outer variable x, and only then will the declaration of the second variable x take place.

In this specific case, we’d get a warning from the compiler, because the first (outer) variable x is being shadowed by the second variable x.

⚡ Warning: in versions prior to 0.5.0, Solidity used the same scoping rules as JavaScript: a variable declared at any location within the function would be visible through the entire function’s scope. That’s why the example below could’ve been compiled in Solidity versions before 0.5.0:

// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.5.0 <0.9.0;
// This will not compile
contract C {
    function f() pure public returns (uint) {
        x = 2;
        uint x;
        return x;
    }
}

The code above couldn’t compile in today’s versions of Solidity because an assignment to variable x is attempted before the variable itself is declared. In other words, the inner variable x‘s scope starts with the line of its declaration.

Conclusion

In this article, we learned about variable and function scopes.

• First, we made a scope overview, introducing ourselves to three different scopes in Solidity.
• Second, we investigated the global scope by studying an appropriate example.
• Third, we looked at the contract scope through an appropriate example.
• Third, learned about the function scope on an appropriate example.
• Fourth, we glanced at C99 scoping rules based on C99 – a C language standard.
• Fifth, we also learned about shadowing and got an idea of why we should be careful about it.

What’s Next?

This tutorial is part of our extended Solidity documentation with videos and more accessible examples and explanations. You can navigate the series here (all links open in a new tab):