Understanding Structs for Custom Data Types

Hello! Welcome to your third lesson in the "Advanced Solidity & Contract Logic" module.

In our last session, you learned how to use mappings to create highly efficient key-value stores. We saw how they are perfect for tracking a single piece of data per key, like a user's token balance. But what happens when you need to store a bundle of related information for each user? For instance, for your token, you might want to track not just a user's balance, but also when they first invested, and whether they have voting rights.

This is where today's topic comes in. Our goal is to define and use structs to create custom, complex data types. Structs are the answer to grouping related data, and when combined with mappings, they form one of the most powerful and common patterns in smart contract development.

For someone with your backend experience, this concept should feel quite natural. A struct in Solidity is analogous to a class in Java or Python (without the methods), or more closely, a type or interface in TypeScript. It's a way to define your own data structure.

What is a Struct?

A struct, short for structure, is a custom-defined data type that can group variables of different data types together under a single name. This is incredibly useful for a few reasons:

• Organization: It keeps your code clean and readable by packaging related data together.
• Complexity: It allows you to build complex data models that represent real-world objects or concepts.
• Efficiency: It can help you get around the "stack too deep" error, which occurs when a function has too many local variables (more than 16), by grouping them into a single struct.

To see this in action, let's start with a video that introduces the basic syntax and demonstrates how to create and use your first struct.

As you saw, the basic syntax is straightforward:

// Define a new custom data type called 'Book'
struct Book {
    string title;
    string author;
    uint pageCount;
    bool isAvailable;
}

// Create a state variable instance of our new type
Book public myFavoriteBook = Book("The Hitchhiker's Guide", "Douglas Adams", 224, true);

The Power Combo: Mappings of Structs

While a single struct instance is useful, the true power of structs is unlocked when you combine them with mappings. Instead of mapping an address to a simple uint balance, you can map an address to a complex struct containing a wealth of information.

This mapping(address => YourStruct) pattern is the backbone of countless smart contracts. It lets you create a database-like structure where each user address points to its own unique data object.

Let's watch a video that builds this exact pattern step-by-step.

Let's apply this to our token project. Imagine we want to store details about each person who invests in our token.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

contract TokenInvestorData {

    // 1. Define the struct
    struct Investor {
        uint tokenBalance;
        uint lastInvestmentTimestamp;
        bool isWhitelisted;
    }

    // 2. Create a mapping from an address to the struct
    mapping(address => Investor) public investors;

    // 3. Write a function to add/update an investor's data
    function recordInvestment(uint amount) public {
        // Create a storage pointer to the struct for the calling address
        Investor storage investor = investors[msg.sender];

        // Update the fields of the struct
        investor.tokenBalance += amount;
        investor.lastInvestmentTimestamp = block.timestamp;
        investor.isWhitelisted = true; // Maybe investing automatically whitelists them
    }

    // Solidity automatically creates a getter for the 'investors' mapping.
    // We can also create a custom getter for convenience.
    function getInvestorBalance(address _investor) public view returns (uint) {
        return investors[_investor].tokenBalance;
    }
}

A quick note on storage vs. memory:
In the recordInvestment function, you see the line Investor storage investor = .... The storage keyword is crucial here. It tells Solidity that the investor variable is not a new copy of the data, but a pointer to the data that already exists in the contract's storage. When you modify investor.tokenBalance, you are directly modifying the data on the blockchain. If you used memory, you would only be changing a temporary copy, and the state on the blockchain would remain unchanged.

Advanced Struct Patterns and Use Cases

Structs can be nested within each other, and you can even have mappings inside a struct. This allows for very sophisticated data modeling.

The following article provides a fantastic, in-depth example of a contract that uses these advanced patterns to track user deposits and withdrawals.

// 1. Define the struct with the required fields
struct VestingSchedule {
    uint totalAllocation;
    uint released;
    bool isVesting;
}

// 2. Create the public mapping
// The key is the beneficiary's address, and the value is their vesting schedule
mapping(address => VestingSchedule) public schedules;

Conclusion

You've now learned how to create your own custom data types using structs. This is a massive step up from working with just primitive types. By combining structs with mappings, you can model almost any data relationship you need for your smart contracts.

Key Takeaways:

• Structs group related variables into a single, custom data type.
• The most common and powerful pattern is mapping(address => MyStruct), which allows you to associate a complex data object with each user.
• You access and modify struct members using dot notation (e.g., investors[addr].tokenBalance).
• When modifying a struct that's stored in a mapping, use a storage pointer to ensure you're changing the data on the blockchain, not a temporary copy.
• You can nest structs and even place mappings inside them, but remember that mappings are not iterable, so you'll need counters to track entries.

Preview of the Next Lesson:
We just saw how the example contract used a mapping and a counter (numDeposits) to keep track of a collection of transactions. This is one way to handle lists of data. In our next lesson, we'll explore Solidity's native solution for ordered collections: arrays. We'll cover how to work with both fixed-size and dynamic arrays and compare their use cases and gas costs to mappings.