Create EOSIO Table In .hpp File With CDT: A How-To Guide

Nov 28, 2025 by Andrew McMorgan 57 views

Creating EOSIO Tables in .hpp Files with CDT: A Comprehensive Guide

Hey Plastik Magazine readers! Ever wondered how to create tables in your EOSIO smart contracts using CDT (Contract Development Toolkit)? It might seem a bit daunting at first, but trust me, it's totally doable. This guide is designed to walk you through the process step-by-step, making it super easy to understand, even if you're just starting out with blockchain development. So, let's dive in and get those tables up and running!

Understanding the Basics of EOSIO Tables and CDT

Before we jump into the code, let's quickly recap what EOSIO tables and CDT are all about. EOSIO is a powerful blockchain platform, and smart contracts are the backbone of any decentralized application (dApp) built on it. Tables, in this context, are like databases within your smart contract, used to store and manage data. Think of them as the digital ledgers where your contract's information lives.

CDT, or Contract Development Toolkit, is a set of tools provided by EOSIO to help developers like us write, compile, and test smart contracts. It includes libraries, headers, and compilers specifically designed for EOSIO, making the development process smoother and more efficient. Using CDT ensures that your contracts adhere to EOSIO's standards and can be deployed without issues. It's kind of like having the right set of instruments for your musical masterpiece – it ensures everything sounds just right!

Now, why would you want to define your tables in a .hpp file? Well, the .hpp file, or header file, is where you declare your contract's structure, including the tables, actions, and data structures. This makes your code more organized and reusable. It's like having a blueprint for your contract, defining all the components and how they fit together. This approach is particularly useful for generic contracts, where you might want to reuse the same table structure across different contracts. By defining the table in a header file, you can simply include it in any contract that needs it, avoiding code duplication and making your life as a developer much easier. Think of it as a modular approach to contract development, where you can plug and play different components as needed.

Step-by-Step Guide to Creating Tables in .hpp

Okay, let's get down to the nitty-gritty and see how to actually create a table in your .hpp file. We'll break this down into manageable steps, so you can follow along easily. Don't worry, we'll keep it super casual and friendly, just like we're chatting over coffee about coding stuff.

1. Setting Up Your Project Structure

First things first, let's talk about project structure. In a typical EOSIO project, you'll have a .cpp file (like mycontract.cpp) where your contract's logic resides, and a .hpp file (like myheader.hpp) where you define your contract's structure. The .cpp file includes the .hpp file, so it knows about the tables and data structures you've defined. This separation of concerns makes your code cleaner and easier to maintain. It's like having a well-organized desk – everything has its place, and you can find things quickly.

For example, you might have mycontract.cpp which contains the main contract logic and imports myheader.hpp. This .hpp file will contain the table definition we're about to create. This setup allows you to keep your table definitions separate from your contract logic, making your code more modular and reusable. It’s a best practice in software development, and it’s especially helpful when dealing with complex smart contracts. Think of it as building with Lego bricks – each brick (or module) has a specific function, and you can combine them in various ways to create different structures.

2. Defining the Table Structure in .hpp

Now, let's dive into the heart of the matter: defining the table structure in your .hpp file. This involves using C++ structs and the EOSIO CDT attributes to define the table's schema. It might sound a bit technical, but it's actually quite straightforward once you get the hang of it.

In your myheader.hpp file, you'll start by defining a struct that represents your table's row structure. This struct will contain the fields (columns) of your table, along with their data types. You'll also need to use special CDT attributes, like [[eosio::table]] and [[eosio::primary_key]], to tell EOSIO how to interpret your struct as a table. These attributes are like annotations that provide extra information to the compiler, letting it know how to handle your code. Think of them as special instructions that guide the compilation process.

Here's an example of what this might look like:

#include <eosio/eosio.hpp>

namespace mycontract {

  struct [[eosio::table]] mytable {
    uint64_t id; 
    std::string name;

    uint64_t primary_key() const { return id; }

    EOSLIB_SERIALIZE(mytable, id, name)
  };

}

Let's break this down:

#include <eosio/eosio.hpp>: This line includes the necessary EOSIO header file, which provides the base classes and functions you'll need for your contract. It’s like importing the essential tools for your project.
namespace mycontract { ... }: This defines a namespace for your contract, which helps to avoid naming conflicts with other contracts or libraries. It's like creating a separate workspace for your project, so your code doesn't interfere with others.
struct [[eosio::table]] mytable { ... }: This declares a struct named mytable and tells EOSIO that it represents a table. The [[eosio::table]] attribute is the magic that makes this happen.
uint64_t id;: This defines a field named id of type uint64_t, which is an unsigned 64-bit integer. This is a common data type for IDs in EOSIO.
std::string name;: This defines a field named name of type std::string, which is a standard C++ string.
uint64_t primary_key() const { return id; }: This defines a method called primary_key that returns the primary key of the table, which in this case is the id field. Every EOSIO table needs a primary key, which is used to uniquely identify each row.
EOSLIB_SERIALIZE(mytable, id, name): This macro tells EOSIO how to serialize the table, which is necessary for storing it on the blockchain. Serialization is the process of converting data structures into a format that can be stored or transmitted. It’s like packing your data into a suitcase so it can be easily moved around.

3. Creating the Table Abstraction

Now that you've defined the table structure, you need to create an abstraction for it. This involves using the eosio::multi_index class, which provides a convenient way to interact with tables in your contract. The multi_index class allows you to perform operations like creating, reading, updating, and deleting rows in your table. It's like having a set of tools for managing your table data.

In your myheader.hpp file, you'll create a new struct that inherits from eosio::multi_index. This struct will take your table's row structure as a template parameter. You'll also need to define the table's code and scope, which are used to identify the table on the blockchain. The code is the contract account name, and the scope is a namespace within the contract where the table is stored. Think of the code as the address of your building, and the scope as the floor where your apartment is located.

Here's how you might do it:

#include <eosio/eosio.hpp>

namespace mycontract {

  struct [[eosio::table]] mytable {
    uint64_t id; 
    std::string name;

    uint64_t primary_key() const { return id; }

    EOSLIB_SERIALIZE(mytable, id, name)
  };

  using mytable_index = eosio::multi_index<"mytable"_n, mytable>;

}

Let's break this down:

using mytable_index = eosio::multi_index<"mytable"_n, mytable>;: This line creates a type alias named mytable_index for the eosio::multi_index class. The first template parameter, "mytable"_n, is a name literal that represents the table's name. The _n suffix is a user-defined literal provided by EOSIO, which converts the string literal into a name object. The second template parameter, mytable, is the struct you defined earlier, which represents the table's row structure. This line essentially creates a class that manages your table data. It's like setting up a database connection so you can interact with your table.

4. Using the Table in Your Contract (.cpp File)

Now that you've defined the table structure and created the table abstraction in your .hpp file, it's time to use it in your contract's .cpp file. This involves including the .hpp file, instantiating the multi_index object, and using its methods to interact with the table. This is where you'll actually be adding, reading, updating, and deleting data in your table.

In your mycontract.cpp file, you'll first need to include the myheader.hpp file. Then, in your contract class, you'll declare a member variable of type mytable_index. This member variable will be your gateway to the table. It's like having a key to the database, allowing you to access and modify the data.

Here's an example of how you might do it:

#include <mycontract.hpp>

namespace mycontract {

  class [[eosio::contract]] mycontract : public eosio::contract {
  public:
    using contract::contract;

    mytable_index _mytable{get_self(), get_self().value()}; 

    [[eosio::action]]
    void addname(uint64_t id, std::string name) {
      require_auth(get_self());
      _mytable.emplace(get_self(), [&](auto& row) {
        row.id = id;
        row.name = name;
      });
    }

  private:

  };

}

EOSIO_DISPATCH(mycontract::mycontract, (addname))

Let's break this down:

#include <mycontract.hpp>: This line includes your contract's header file, which contains the table definition. It’s like importing the blueprint for your table.
mytable_index _mytable{get_self(), get_self().value()};: This line declares a member variable named _mytable of type mytable_index. The constructor takes two arguments: the contract's account name (obtained using get_self()) and the table's scope (also obtained using get_self().value()). This creates an instance of the multi_index class, which you'll use to interact with your table. It’s like creating a connection to your database.
[[eosio::action]] void addname(uint64_t id, std::string name) { ... }: This defines an action named addname that can be called on the contract. Actions are the entry points for interacting with your contract. It’s like defining the functions that users can call to interact with your smart contract.
require_auth(get_self());: This line checks that the contract's account has authorized the action. Security is crucial in smart contracts, so you always need to verify that the caller has the necessary permissions. It’s like checking the user's credentials before allowing them to access sensitive data.
_mytable.emplace(get_self(), [&](auto& row) { ... });: This line uses the emplace method of the multi_index class to add a new row to the table. The first argument is the payer, which is the account that will pay for the storage of the new row. The second argument is a lambda function that initializes the new row. It’s like inserting a new record into your database.
row.id = id;: This line sets the id field of the new row to the value passed in as an argument to the addname action.
row.name = name;: This line sets the name field of the new row to the value passed in as an argument to the addname action.

5. Compiling and Deploying Your Contract

Once you've written your contract code, you'll need to compile it and deploy it to the blockchain. This involves using the EOSIO CDT compiler (eosio-cpp) to generate the WebAssembly (WASM) and ABI files for your contract. The WASM file contains the compiled bytecode of your contract, and the ABI file describes your contract's interface, including the actions and tables. These files are like the compiled executable and the API documentation for your contract.

To compile your contract, you'll typically use a command like this:

eosio-cpp -abigen mycontract.cpp -o mycontract.wasm

This command tells the compiler to generate both the WASM and ABI files for your contract. The -abigen flag tells the compiler to generate the ABI file, and the -o flag specifies the output file name for the WASM file.

Once you have the WASM and ABI files, you can deploy your contract to the blockchain using the cleos command-line tool. This involves setting the contract on an EOSIO account and uploading the WASM and ABI files. It’s like publishing your application to the world.

Best Practices and Tips for Table Creation

Before we wrap up, let's talk about some best practices and tips for creating tables in EOSIO smart contracts. These are the little nuggets of wisdom that can save you time and headaches in the long run.

1. Keep Your Table Structures Simple

When designing your table structures, it's a good idea to keep them as simple as possible. This makes your code easier to understand and maintain, and it can also improve performance. Avoid using complex data structures or deeply nested tables, as this can make your contract more difficult to work with. Think of it as the KISS principle – Keep It Simple, Stupid!

2. Use Appropriate Data Types

Choosing the right data types for your table fields is crucial for both efficiency and data integrity. EOSIO provides a variety of data types, including integers, strings, and custom types. Use the smallest data type that can accommodate your data, as this will save storage space and improve performance. It’s like choosing the right tool for the job – using a sledgehammer to crack a nut is overkill!

3. Consider Indexing

If you need to query your table based on fields other than the primary key, consider adding secondary indexes. Indexes can significantly speed up query performance, especially for large tables. EOSIO provides built-in support for secondary indexes, so you can easily add them to your tables. Think of indexes as the index in a book – they allow you to quickly find the information you need without having to read the entire book.

4. Handle Data Serialization Carefully

Data serialization is the process of converting data structures into a format that can be stored on the blockchain. EOSIO uses a specific serialization format, so you need to make sure your tables are properly serialized. The EOSLIB_SERIALIZE macro, which we used earlier, takes care of this for you, but it's important to understand what's going on under the hood. Think of serialization as packaging your data for shipping – you need to make sure it's properly packed so it doesn't get damaged in transit.

5. Test Your Contracts Thoroughly

Last but not least, always test your contracts thoroughly before deploying them to the mainnet. This includes testing your table operations, such as adding, reading, updating, and deleting rows. Use unit tests and integration tests to ensure that your contract behaves as expected. Testing is like proofreading your work before submitting it – you want to catch any errors before they become a problem.

Conclusion: Mastering EOSIO Table Creation

So, there you have it, guys! Creating tables in EOSIO smart contracts using CDT might seem a bit complex at first, but with a little practice, you'll be a pro in no time. Remember, the key is to understand the basics, follow the steps carefully, and always test your code. By defining your tables in .hpp files, you can create more organized, reusable, and maintainable smart contracts.

We've covered a lot in this guide, from setting up your project structure to compiling and deploying your contract. We've also discussed best practices and tips for table creation, so you can avoid common pitfalls and write efficient code. Now it's your turn to put this knowledge into practice and build some awesome dApps on EOSIO. Happy coding!