One great combination is using Rust with the Gear Protocol. In this guide, I'll show you how to build and deploy a smart contract using Rust and the Gear Protocol. Whether you're new to this or have some experience, this article will help you get started with clear and easy-to-follow steps.

Prerequisites

1. Have basic Rust knowledge.
2. Having a basic understanding of decentralization.

Table of Contents

1. Introduction to Vara Network & Gear Protocol.
2. Why Use the Web2 Analogy?
3. Message-based Communication.
4. Illustration
5. Vara Network's Role.
6. First Project – Reading a Joke
7. Next Project – input-msg
8. Metadata & State
9. Third Project – Building Messages
10. Final Project – Battle Showdown
11. Conclusion.

Introduction to Vara Network & Gear Protocol.

Vara Network

Think of Vara as the sturdy foundation of blockchain technology. It's a layer-1 blockchain, meaning that it's at the core of transactions, ensuring that they are secure and decentralized. Vara uses Nominated Proof-of-Stake (NPoS) for agreement, making it reliable and efficient.

Furthermore, Vara Network distinguishes itself through its novel Actor Model, an architecture characterized by isolation and asynchronous messaging. This paradigm shift in smart contract execution imbues Vara Network with unparalleled security and scalability, setting it apart from conventional blockchain platforms.

Gear Protocol

Gear Protocol is like a toolbox for developers. It's a smart contract engine that makes building decentralized apps (dApps) faster, safer, and cheaper. By using substrate technology and WebAssembly (Wasm), Gear makes it easy for developers to create dApps that run smoothly and securely.

Gear's utilization of the Wasm virtual machine serves as a cornerstone of its efficiency. By harnessing the power of Wasm, developers can transcend language barriers, seamlessly integrating existing codebases and accelerating the development lifecycle. This fusion of familiarity and performance paves the way for a new era of dApp creation, where speed, security, and scalability converge harmoniously.

In simpler terms, Vara Network and Gear Protocol work together to make blockchain technology more user-friendly and secure for building and using decentralized apps.

Why Use the Web2 Analogy?

Understanding message-based communication, particularly within the context of Gear Protocol, can be quite challenging. To gain a clearer understanding, I delved into the documentation and conducted additional research. Eventually, I stumbled upon an analogy that made it all click: the analogy of web HTTP requests, specifically the POST method.

Let's dissect this analogy step by step. Consider the familiar scenario of a user visiting a website like google.com and interacting with the search bar. When the user enters a search query and hits enter, what's happening behind the scenes is akin to a POST HTTP request being sent.

Here's how it unfolds:

1. User Interaction: The user initiates the action by typing a search query into the search bar and hitting enter. This action triggers a request for information.
2. Client Acknowledgment: Google's website, acting as the client-side user interface (UI), acknowledges the user's input and prepares to send a request to the server for processing.
3. Request Sent: Just like when you hit enter after typing a query, Google's website sends a POST request to its server, conveying the user's search query.
4. Server Processing: Upon receiving the POST request, Google's server processes the query, searching its vast index for relevant information.
5. Response Generation: After processing the query, Google's server generates a response containing the search results.
6. Response Sent: Finally, Google's server sends the response back to the client (the user's web browser), completing the communication cycle.

In this analogy, the user represents the initiator of the communication, the client (UI) serves as the intermediary between the user and the server, and the server acts as the responder, processing requests and generating responses.

By drawing parallels between message-based communication in Gear Protocol and the familiar concept of web HTTP requests, we can better grasp the dynamics at play. Just as understanding how web requests facilitate communication between users and servers is essential for navigating the internet, comprehending message-based communication in Gear Protocol is crucial for building and interacting with decentralized applications effectively.

how the POST method works

Message-based Communication

Similarly, the Gear Protocol operates based on user or program interactions.
Note: Programs on Gear can also interact with each other.
So here is a detailed explanation to the whole communication flow in Gear.

User Interaction and @gear-js/api

When a user (actor) interacts with the dApp's UI elements (like buttons or forms), _@gear-js/api_ (which is integrated into the UI) captures these interactions. Based on the interactions, it extracts information and potentially pre-defined message formats, and then contracts a message object containing the user's intent or request.

How to Send Messages

The constructed message object encapsulates the user's input and becomes the data @gear-js/api transmits across the Vara Network to the Gear crate within the program.

How the Program Receives and Processes Messages

Gear (crate) delivers the message object to the appropriate program deployed on the Vara Network based on the location the user initiated the action. The Gear crate within the program utilizes functions like msg::load() and access the delivered message object, which the program extracts information (such as payload, source, messsageId) from, and process it according to how it's designed by the developer.

How to Generate a Reply

Based on the processed input, the program creates a new message object containing a reply (response in web2) to the user's action or interaction (called reply) to or for the user.

Note, the program typically doesn't send the original message object back, it generates a new one based message received, which a reply is sent back to be received by @gear-js/api using the gstd crate from the program utilizing functions like the msg::reply or msg::reply_bytes.

UI Update

@gear-js/api, within the dApp, receives the reply message object delivered by the gstd crate from the program across the Vara Network and extracts the response data from the reply object, and finally updates the UI reflecting the program's response to the user's interaction.

And that's pretty much the communication between the Users, Client(dApp), Gear Protocol(gstd), and finally Vara Network.

Illustration

Let's discuss more about the diagrams below, and how they each interact with each other.

UI Update

This illustration above is just a bird's eye view of how communication flows from the user to the program. I'll provide a complete illustration for more clarity. But before that, let's break the overview illustration into three stages.

Initial Interaction Stage

As said earlier, this is when the user interacts with the program, both @gear-js/api and gstd.

Initial Interaction Stage

Business/Program Logic

This section depicts the communication between the program and Gear within Vara Network. The gstd is used by the program to access the transmitted message (msg::load()) from the initial stage to perform business logic.

Business/Program Logic

Reply (Response)

This final stage shows how user feedback is delivered to the user or program. @gear-js/api translates it if necessary, and then updates the dApp's UI with the results. This allows the user to see the outcome of their action within the dApp.

Reply(Response)

That's great, right? This should help you understand how messages are passed from the client to the program. But what does Vara Network role mean here? Earlier I said that, the message object get transmitted across the Vara Network, but I didn't say how. Let's explain that.

Vara Network's Role

In Vara, all participants, including user interfaces (through @gear-js/api) and smart contracts (programs & gstd), are considered as actors. Another point to know is that, actors don't directly call functions within other actors (as in, programs interacting with other programs or even users).

Instead, they send messages containing data or instructions. So in our explanation of the message-based communication, Vara serves as the underlying decentralized network infrastructure for communication of our system (dApps). It provides a secure and reliable platform for message transmission across distributed network of nodes. And since Vara utilize a consensus mechanism NPoS (Nominated Proof-of-Stake), it ensures network security and transaction validation.

Getting Our Hands Dirty

In order to build upon the above information I provided, you and I need to get our hands dirty by building and deploying programs with additional explanation for a clearer understanding.

Let's get started.

First Project - Reading a Joke

In this project, you're going to interact with and deploy your smart contract on Vara Network, and receive a reply message back.

This is just a simple project, and nothing too complex. I chose this example project because it aligns with the analogy I gave earlier.

Currently, this project should be fine when running it on your Windows system. In case you get an error, scroll to the part of this article with a guide for setting up a Windows Subsystem for Linux (WSL), since it would allow you to run a Linux environment, including command-line tools and applications, directly on Windows, without the overhead of a traditional virtual machine or dual boot setup.

To get started, create a directory named freecodecamp-gear-protocol. Since you'll be building about fours projects, and I think it is important on how you can setup your projects for Gear Protocol.

So in your freecodecamp-gear-protocol directory, create a Cargo.toml file with the following code:

[workspace]
resolver = "2"
members = []


[workspace.package]
name = "freecodecamp-gear-protocol"
version = "0.1.0"
edition = "2021"
authors = ["Rocky Essel"]
license = "MIT"
publish = false

[workspace.dependencies]
# Internal Crates
# External Crates

For someone new to Rust or used to creating single projects, I'll guide you through understanding and setting up a workspace in Rust, making it easy to grasp.

Understanding Your Workspace

A workspace in Rust is a set of packages (crates) that are managed together. Let's break down the key sections: [workspace], members, [workspace.package], and [workspace.dependencies]. So think of this like a cabin for your shoes, where each pair of shoes is a crate (package) that you want to keep organized.

[workspace] Section

The [workspace] section defines the overall workspace. It typically contains multiple members.

resolver = "2": Specifies the version of Cargo's feature resolver to use, improving how dependencies are managed across the workspace.

members: Lists the crates that are part of the workspace. When you add a project with cargo new --lib sneakers or boots, the members section of the Cargo.toml is populated with the name of the project you created.

If not added automatically, you can add them yourself.

For example:

members = ["sneakers", "boots"]

[workspace.package] Section

This section provides metadata for the entire workspace as if it were a single package.

• name: The name of the workspace package.
• version: The version of the workspace package.
• edition: The Rust edition being used (e.g., "2021").
• authors: List of authors.
• license: The license for the workspace package.
• publish: Indicates whether the workspace package should be published to crates.io.

Example:

[workspace.package]
name = "my-shoe-collection"
version = "0.1.0"
edition = "2021"
authors = ["Your Name"]
license = "MIT"
publish = false

[workspace.dependencies] Section

Lists dependencies that apply to the entire workspace. Meaning that every crate whether external or internal added to the [workspace.dependencies] is accessible to every project you create under project workspace. So below is how both external and internal crate are made accessible to other project.

Note: For internal crate, you need to add them yourself.

Internal Crates: Add internal crates like this:

sneakers = { path = "sneakers" }
boots = { path = "boots" }

External Crates: Add external crates like this:

polish = "1.0"

Example Cargo.toml

Here's an example combining these sections:

[workspace]
resolver = "2"
members = ["sneakers", "boots"]

[workspace.package]
name = "my-shoe-collection"
version = "0.1.0"
edition = "2021"
authors = ["Your Name"]
license = "MIT"
publish = false

[workspace.dependencies]
# Internal crate
sneakers = { path = "sneakers" } 
boots = { path = "boots" } 

# External crate
polish = "1.0"

So, here's how you set up a workspace for your project to manage multiple crates (sub-projects) and share dependencies and configuration settings across them. I spent quite some time understanding this, so I thought I'd share it with you all to make it easier.

To build your first smart contract, run the command below in your parent directory (freecodecamp-gear-protocol) on your terminal.

cargo new --lib receive-joke

.freecodecamp-gear-protocol
├── Cargo.toml
└── receive-joke
    ├── Cargo.toml
    └── src
        └── lib.rs

2 directories, 3 files

Head over to your freecodecamp-gear-protocol/receive-joke/Cargo.toml, and this is how you access crates, and configuration from the workspace directory(main) using .workspace=true, like below;

[package]
name ="receive-joke"
version.workspace = true
edition.workspace = true
authors.workspace = true
license.workspace = true
publish.workspace = true

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

[dependencies]

Next, create a build file in your receive-joke directory with path likereceive-joke/build.rs, and paste the code below. Now, the build.rs helps you to build your project into .wasm file, that is used to deploy your smart contract.

build.rs:

fn main() {
    gear_wasm_builder::build();
}

Currently, you have't install the nesscessary crate to help create your smart contract. Therefore, add the following crate to your workspace dependency.

Cargo.toml:

[workspace]
resolver = "2"
members = ["receive-joke"]


[workspace.package]
name = "freecodecamp-gear-protocol"
version = "0.1.0"
edition = "2021"
authors = ["Rocky Essel"]
license = "MIT"
publish = false

[workspace.dependencies]
# Internal Crates

# External Crates
gstd = "1.4.1"
gmeta = "1.4.1"
gtest  = "1.4.1"
gear-wasm-builder = "1.4.1"
parity-scale-codec = { version = "3.6.12", default-features = false }
scale-info = { version = "2.11.3", default-features = false }

For your first project, only gstd would be used, so like add that external crate to your receive-joke's Cargo.toml. Like below:

[dependencies]
gstd.workspace = true


[build-dependencies]
gear-wasm-builder.workspace = true

If you reached here without any errors, well done my friend. Next, is to clear any code in freecodecamp-gear-protocol/receive-joke/src/lib.rs. Let's move on to the next step.

In Gear Protocol, there are entry points. An entry point serves as a gateway or door to your code. Gear has a few entry points, namely:

state(),
handle(),
handle_reply(),
init(),
handle_signal(),

Each entry point plays a significant role. For example, init() is called when the smart contract(.wasm) is deployed, allowing you to set certain conditions or variables or even other functions that need to be executed for smooth sailing of your smart contract or program.

However, it's optional, meaning that you can choose to include or exclude it depending on your project, but it still gets executed, and it is the first message you'll see once you deploy your smart contract.

The handle() method is crucial as it contains most of the business logic. It's mandatory to include your program. More light will be shared on the entry points as you move forward.

Now, paste the following code into your receive-joke/src/lib.rs:

#![no_std]

use gstd::msg;

#[no_mangle]
extern "C" fn handle() {
    // Send a reply(in HTTP GET Request, you'd use "response").
    msg::reply_bytes(
        "What did the dirt say to the rain? If you keep this up, my name will be mud!",
        0,
    )
    .expect("Unable to reply");
}

The code above defines a function handle that, when called, sends a message you've defined as a response using the gstd::msg functionality. This gstd is a crate provided by Gear Protocol, to send and receive messages, and this is crucial for programs running on Vara Network to communicate with each other and external systems. And the reply_bytes send a new message as a reply to the message that is currently being processed.

Time to deploy and send your first message and recieve your joke reply. In your terminal, run the following command to build your program into .wasm.

Usually, I use cargo check for check for errors first, before using the build command below, either way is fine.

cargo build --release

After the build is completed, follow the structure below to locate your .wasm file in the path below:

.freecodecamp-gear-protocol
├── Cargo.lock
├── Cargo.toml
├── receive-joke
│   └── ...
└── target
    ├── ...
    └── wasm32-unknown-unknown
        ├── ...
        └── release
            ├── receive_joke.opt.wasm <--- Optimized for deployment.
            └── receive_joke.wasm

How to Deploy Your Smart Contract

Just like in other blockchain tools, that help you deploy your smart contract from the terminal, IDEA is where you deploy your smart contract and interact with it. We'll be exploring the interface in a bit. So finally, head over to IDEA so start familiarizing yourself with your deployment environment.

Smart Contract Deplyment Web App- IDEA

1. Step one, click on Upload program, then select or drag your .opt.wasm inside the modal. This takes you to the upload page, where you can change names, enter values for the payload, or change the payload type. For now, let's leave everything as it is, and click on the Calculate, which will enter a 0.00015 gas fee value for uploading your program.

Note: You can either set the gas limit yourself, or click on Calculate to allow the program to generate one for you.

Upload Page Details

At this point, click on the Upload Program, and click on the Submit button.

Transaction Details- PopUp

When you submit, you'll be prompted you sign into a your wallet, and approve.

Wallet - SubWallet

After the approval, a toast message should be displayed at the right-hand corner your computer/laptop screen for you to see the status of your program, whether it failed or succeeded.

Assuming it's a success, click on the Programs on the sidebar, then BOOM!, there's your program. Click on it, and let's explore.

Upon deploying, the first thing you see is the program ID, but after a few seconds, the name of your program would be shown.

Smart Contract Block - Page

Earlier, I said that when you deploy a program, the init() function is executed regardless of whether you defined it in your project or not, and that's what you see in the Messages section. Below is a simple illustration for you to familiarize and understand the information about your program.

Page Illustration

Now, it's time to send a message to your program and receive a reply back, which is our joke. Remember, you're not inputting any values, you're just performing a simple action to receive a reply from the program. So click on Calculate and press the Send Message (that's the action or interaction) button.

Performing an action - Initial Stage

After the message has been sent, a success toast will popup. Then head back to your program by clicking on the Cancel button, and you'll see two additional messages.

Remember, the blue color with the arrow represent the message you sent, and the green represents the reply you've received. So click on the replied message to see the joke, which says: What did the dirt say to the rain? If you keep this up, my name will be mud!.

Receiving Reply & More Illustration

Now, you're finally done with this project. In the next project, you'll be sending data or information to your program, and having it return a reply with your entered value attached to it. Here is the program deployed on the Vara Network.

Important Information

Though I've provided some context to the picture above, I want to expand on it. Both the Source and Destination takes an address that can be either a user (actor) and a program (actor), or even a message object.

Next Project – input-msg

Just like the illustration earlier, you're going to interact with your program by sending an input value to your smart contract deployed on [IDEA](https://idea.gear-tech.io/programs?node=wss%3A%2F%2Ftestnet.vara.network). IDEA is your deployment environment where you deploy your smart contract on the Vara Network.
The point here is for you to load input values from your user, and process it by concatenating a string to the user's input value: "We've received your query. {user's-input}".

This is the reply you'll send back to the user that sends a message (input value).

So in your freecodecamp-gear-protocol directory, run the command below to add another member to your freecodecamp-gear-protocol/Cargo.toml.

cargo new --lib input-msg

After adding another member or project in the freecodecamp-gear-protocol, your path should be freecodecamp-gear-protocol/input-msg.

Earlier, I made mention of how to access input values into the smart contract or program by using gstd, which has a function or method called load(). For the next step, clear your freecodecamp-gear-protocol/input-msg/src/lib.rs, and paste the following code and run cargo check.

#![no_std]

use gstd::{msg, prelude::*};

#[no_mangle]
extern "C" fn handle() {
    let new_msg = msg::load().expect("Unable to create string");
    let reply_msg = format!("We've received your query {}", new_msg);
    msg::reply_bytes(reply_msg, 0).expect("Unable to reply.");
}

The check fails, but why? Well, the load() function has a type of unknown. And since Rust is a strongly typed language, it has to always know the type before hand, which wasn't the case, so it failed to build the project.

This should tell you that the load() doesn't have a type, and it is up to you to set the right data type, and failure to do so would result in some frustrating errors like below.

Debugging

Now if you were to use a single project and not a workspace, then debugging the error might have easy like below.

  error[E0282]: type annotations needed
   --> C:\Users\user\Desktop\2024\web3\re-gear\input-msg\src\lib.rs:7:9
    |
  7 |     let new_msg = msg::load().expect("Unable to create string");
    |         ^^^^^^^
    |
  help: consider giving `new_msg` an explicit type
    |
  7 |     let new_msg: /* Type */ = msg::load().expect("Unable to create string");
    |                ++++++++++++

But since you and I are using a workspace, it makes debugging a little difficult. This is my error message i got, when dubgging this error.

  error[E0275]: overflow evaluating the requirement `gstd::parity_scale_codec::Compact<_>: gstd::Decode`
    |
    = help: consider increasing the recursion limit by adding a `#![recursion_limit = "256"]` attribute to your crate (`input_msg`)
    = note: required for `gstd::parity_scale_codec::Compact<_>` to implement `gstd::Decode`
    = note: 125 redundant requirements hidden
    = note: required for `gstd::parity_scale_codec::Compact<<_ as CompactAs>::As>` to implement `gstd::Decode`

  For more information about this error, try `rustc --explain E0275`.
  error: could not compile `input-msg` (lib) due to 1 previous error
  warning: build failed, waiting for other jobs to finish...
  error: cargo command run failed: exit status: 101
warning: build failed, waiting for other jobs to finish...

And if you look closely, you can tell that the input-msg is what creating the error. In this case, run rustc --explain E0275, which output an suggestion like this

An evaluation of a trait requirement overflowed.

Erroneous code example:

trait Foo {}

struct Bar<T>(T);

impl<T> Foo for T where Bar<T>: Foo {}

This error occurs when there was a recursive trait requirement that overflowed before it could be
evaluated. This often means that there is an unbounded recursion in resolving some type bounds.

To determine if a T is Foo, we need to check if Bar<T> is Foo. However, to do this check, we need to
determine that Bar<Bar<T>> is Foo. To determine this, we check if Bar<Bar<Bar<T>>> is Foo, and so on. This
is clearly a recursive requirement that can't be resolved directly.

Consider changing your trait bounds so that they're less self-referential.

Now, though, compared to the first error message, this message doesn't provide a direct solution, it does tells you that, there's a type error in your code. And the reason is that, the load() can load any data type, so you should always defined a type for it.

#![no_std]

use gstd::{msg, prelude::*};

#[no_mangle]
extern "C" fn handle() {
    let new_msg: String = msg::load().expect("Unable to create string");
    let reply_msg = format!("We've received your query {}", new_msg);
    msg::reply_bytes(reply_msg, 0).expect("Unable to reply.");
}

In the above code, you've added a type String to the new_msg because that's the type you're expecting. Now run the build command, and deploy the file .opt.wasm to IDEA.

.freecodecamp-gear-protocol
├── receive-joke
├── Cargo.toml
├── input-msg
│   └── ...
└── target
    ├── ...
    └── wasm32-unknown-unknown
        ├── ...
        └── release
            ├── input_msg.opt.wasm <--- Optimized for deployment.         
            ├── input_msg.wasm
            ├── receive_joke.opt.wasm
            └── receive_joke.wasm

When you're done, go to your program and click on the Send Messages. Type any value into the payload field, and it should be a type of String.

Submit and approve and head back to your program, then select your reply_message box and you should see your reply message.

Smart Contract - Reply Message

You can find the program here on the Vara Network.

Metadata & State

Metadata and state goes hand in hand with each other. In order for your client application to allow users to interact or request data(state) from your smart contract, you need to define both the metadata and state, and even if the state is defined, and the metadata was not provided, you cannot access the any data.

So let's take each step by step.

Metadata

In the Gear Protocol world, metadata is like a blueprint for defining how different parts of a decentralized app (dApp) talk to each other. It's similar to how interfaces or types work in TypeScript. These blueprints describe how things like initial data type to expect, handling messages, and swapping data happen in the dApp, whether In, Out, and InOut.

When we make clear blueprints, it helps developers make sure that all the different parts of the dApp understand each other's data formats. This makes it easy for the smart contract (program-actor) and the client side app to share data smoothly.

To create these blueprints for your program, we use the gmeta tool. It helps us define these blueprints by outlining how different interactions work and what kinds of data they involve.

So, think of metadata in your program as similar to how interfaces/types work in TypeScript. They help organize how the different parts of your dApp communicate and understand each other's data.

Example Of A Metadata

use gmeta::{InOut, Metadata, Out};

pub struct ProgramMetadata;

// Be sure to describe all the types.
// But if any of the endpoints is missing in your program, you can use ();
// as indicated in the case of `type Signal`.

impl Metadata for ProgramMetadata {
    type Init = InOut<MessageInitIn, MessageInitOut>;
    type Handle = InOut<MessageIn, MessageOut>;
    type Others = InOut<MessageAsyncIn, Option<u8>>;
    type Reply = String;
    type Signal = ();
    type State = Out<Vec<Wallet>>;
}

The above is an example of how it is defined. Don't worry if you don't understand it now, I'll cover more into details later. Now let's talk about the state.

State

In Gear Protocol, the state function serves as a dedicated storage space within a program. This storage allows us to store and retrieve data as needed. Since this data is stored in persistent memory, it remains accessible even after the contract stops running. What's fascinating is that anyone with access to the blockchain can view this stored data. The state function doesn't alter or modify the blockchain itself. Instead, it simply provides a way to access stored data within the program.

Here is an example of a state function:

// Describe state structure
#[derive(TypeInfo, Decode, Encode, Clone)]
pub struct Messages {
    pub id: ActorId,
    pub content: String,
}

// Declare and initialize the state
static mut MESSAGES: Vec<Messages> = Vec::new();

#[no_mangle]
extern "C" fn state() {
    msg::reply(unsafe { MESSAGES.clone() }, 0).expect("Failed to share state");
}

When the state function is called, it returns a list of wallets data stored within the program. This means that once a program is deployed on the blockchain, anyone can read its state.

Additionally, developers have the flexibility to create custom programs that can read the state. This empowers you and I to tailor our data access methods according to the specific needs for our dApp, even if the primary program undergoes changes.

The key takeaway is that, the state function facilitates access to data stored in smart contracts. It's worth noting that both users and other programs can access the state of a program, providing a versatile means of interacting with stored data.

Third Project - Building Messages

In our last project input-msg, we didn't keep track of the messages that got sent. So in this project, we'll cover the metadata and state.

Run the command below to create your project in /freecodecamp-gear-protocol/:

cargo new --lib messages

Next, add your build.rs file, and make the workspace dependencies available to the /freecodecamp-gear-protocol/messages.

Adding Metadata to Messages

To setup a metadata for your project, you need to create an additional crate to manage that, so cd into messages, and run the command below.

cargo new --lib io

In your freecodecamp-gear-protocol/messages/io/Cargo.toml, copy and paste the following code:

[package]
name = "messages-io"
version.workspace = true
edition.workspace = true


[dependencies]
gstd.workspace = true
gmeta.workspace = true

Here, I changed the name from io to messages-io, and the reason is for me to identify, and separate it for other io's in the workspace. And add the dependencies.

In order to use the io in your workspace, you need to go the freecodecamp-gear-protocol/Cargo.toml, and add a path from your io to your workspace, which you can then use in any of the projects that need struct, enum, and method.

In freecodecamp-gear-protocol/Cargo.toml:

[workspace]
resolver = "2"
members = ["receive-joke","input-msg"]


[workspace.package]
name = "freecodecamp-gear-protocol"
version = "0.1.0"
edition = "2021"
authors = ["Rocky Essel"]
license = "MIT"
publish = false

[workspace.dependencies]
# Internal Crates
messages-io={path = "messages/io"} < ---- Here

# External Crates
gstd = "1.4.1"
gmeta = "1.4.1"
gtest  = "1.4.1"
gear-wasm-builder = "1.4.1"
parity-scale-codec = { version = "3.6.12", default-features = false }
scale-info = { version = "2.11.3", default-features = false }

And that's the Internal Crate I talked about earlier. Next, you need to include the messages-io in your messages project, like below:

[package]
name="messages"
version.workspace = true
edition.workspace = true
authors.workspace = true
license.workspace = true
publish.workspace = true


[dependencies]
gstd.workspace = true
messages-io.workspace = true <---

[build-dependencies]
gear-wasm-builder.workspace = true
messages-io.workspace = true < ---

The reason for adding messages-io.workspace to both the [dependencies] and [build-dependencies] is to make the struct, enums, pub variables and methods accessible to messages/src/lib.rs, and messages/build.rs using messages-io.workspace.

Metadata in io/src/lib.rs

#![no_std]

use gmeta::{InOut, Metadata, Out};
use gstd::{prelude::*, ActorId, Vec};

pub struct MessageMetadata;

pub static mut MESSAGES: Vec<User> = Vec::new();

pub struct Message {
    pub id: ActorId,
    pub content: String,
}

impl Metadata for MessageMetadata {
    type Init = InOut<Message, String>;
    type Handle = InOut<Message, String>;
    type State = Out<Vec<Message>>;
    type Reply = ();
    type Others = ();
    type Signal = ();
}

To implement the logic of the message-handling system for your program or smart contract, understanding how to set the metadata of your program is crucial.
Therefore, much attention is needed here.

The MessageMetadata struct you've defined implements the Metadata trait, which then structures the message metadata for the program. Also, a mutable static variable MESSAGES is declared to store all the messages you and your users send to the program. And since it’s a mutable static variable, unsafe code will be required to modify it due to Rust's safety guarantees around mutable static variables.

The Message struct is defined with two fields: id (sender's identifier) and content (the message text).

The Metadata trait is implemented for MessageMetadata, defining several associated types. The Init type is set to InOut<MessageInit, String>, specifying the input-output types for the initialization phase. \

This means that when the contract is initialized, it will accept a MessageInit type and return a String. The Handle type is set to InOut<Message, String>, specifying the input-output types for handling messages. It accepts a Message type as input and returns a String.

The State type is set to Out<Vec<Message>>, defining the state output type, meaning that the state of the contract will be a vector of Message objects, and it doesn’t accept any input to retrieve this state. The Reply, Others, and Signal types are all set to (), indicating no additional reply, other types, or signals are used in this case.

Further Context of its usage.

In this system, the metadata definition specifies how the smart contract should handle initialization and message handling. During the initialization phase (Init), when the contract is deployed on the Vara Network, it uses the Init type to set up the initial state. The input is expected to be of type MessageInit, and the output will be a String. During deployment, you provide your ID and message content, which the contract processes using the init() method.

After deployment, the contract can handle new messages using the Handle type, which expects a Message type as input and returns a String as a response. This functionality is useful for adding new messages to the MESSAGES vector. For state management (State), the contract’s state is a list of messages (Vec<Message>), and it doesn’t accept any input to retrieve the state but outputs the current state when queried.

So to summarize, the code in freecodecamp-gear-protocol/messages/io/src/lib.rs defines the structure and behavior of a message-handling smart contract, specifying how it initializes, handles messages, and manages state.

Building the Metadata

In order to build your project with the metadata, you need to modify the build.rs, which initially looks like below:

fn main() {
    gear_wasm_builder::build();
}

There's nothing wrong with using the above code, but if you plan to build your program and deploy on the blockchain to use it on the client or anywhere else, it would be impossible to interact with your smart contract if the metadata is not defined. Think of it like ABI in other blockchain environment.

So replace the code with:

use messages_io::MessageMetadata;

fn main() {
    gear_wasm_builder::build_with_metadata::<MessageMetadata>();
}

Finally, you would be handling the logic for your smart contract in the messages/src/lib.rs using the handle() function.

Here is the code for the lib.rs:

#![no_std]

use gstd::{exec, msg, prelude::*, ActorId};

use messages_io::*;

#[no_mangle]
extern "C" fn init() {
    let init: Message = msg::load().expect("Unable to decode Message");
    let init_message = Message {
        id: init.id,
        content: init.content,
    };

    unsafe { MESSAGES.push(init_message) };    
    msg::reply_bytes("Successfully initialized", 0).expect("Failed to initialize successfully.");
}


#[no_mangle]
extern "C" fn handle() {

    let message_handler: Message = msg::load().expect("Unable to decode Message");
    let message = Message {
        id: message_handler.id,
        content: message_handler.content,
    };
    unsafe { MESSAGES.push(message) };
    msg::reply_bytes("Message sent successfully.", 0).expect("Failed to send  reply message.");
}


#[no_mangle]
extern "C" fn state() {
    msg::reply(unsafe { MESSAGES.clone() }, 0).expect("Failed to share state");
}

Initialization Function (init)

#[no_mangle]
extern "C" fn init() {
    let init: Message = msg::load().expect("Unable to decode Message");
    let init_message = Message {
        id: init.id,
        content: init.content,
    };

    unsafe { MESSAGES.push(init_message) };
    msg::reply_bytes("Successfully initialized", 0).expect("Failed to initialize successfully.");
}

The init function is the entry point for initializing the smart contract. It is marked with #[no_mangle] to prevent Rust from applying name mangling, making the function accessible from the smart contract runtime.

The function begins by loading the initial message from the input payload using msg::load(). This message is expected to be of type Message, and if decoding fails, the function will panic with an error message. Next, a new Message instance is created from the loaded data. This new message is then added to the global MESSAGES vector, which is a mutable static variable marked as unsafe due to potential data races. Finally, the function sends a reply indicating successful initialization using msg::reply_bytes. If this reply fails, the function will panic.

Message Handling Function (handle)

#[no_mangle]
extern "C" fn handle() {
    let message_handler: Message = msg::load().expect("Unable to decode Message");
    let message = Message {
        id: message_handler.id,
        content: message_handler.content,
    };
    unsafe { MESSAGES.push(message) };
    msg::reply_bytes("Message sent successfully.", 0).expect("Failed to send  reply message.");
}

The handle function is designed to handle incoming messages after the contract is deployed. Like the init function, it is marked with #[no_mangle] to ensure it can be called from the smart contract runtime. The function begins by loading the incoming message from the input payload. This message is decoded into a Message struct, and if decoding fails, the function will panic.

A new Message instance is then created from the decoded data and added to the global MESSAGES vector using an unsafe block. The function then sends a reply indicating that the message was sent successfully. If the reply fails, the function will panic.

State Query Function (state)

#[no_mangle]
extern "C" fn state() {
    msg::reply(unsafe { MESSAGES.clone() }, 0).expect("Failed to share state");
}

The state function allows querying the current state of the smart contract. It is also marked with #[no_mangle] for the same reasons as the previous functions. The function replies with a cloned version of the global MESSAGES vector, containing all the messages that have been added so far. This is done within an unsafe block due to the mutable static variable. If the function fails to send the state, it will panic.

So this code simply defines a smart contract with three main functions: init for initialization, handle for processing incoming messages, and state for querying the current state of the contract. Where each function carefully manages the global MESSAGES vector.

Deployment on the Vara Network

Now you're done with this project, and hope you learned and have understood most of what I've written. In our next project, you'll be building something a bit more complex than this. So let's begin.

Here is the program deployed on Vara Network, and this is the entire repository for the 3 projects we've built so far. The next project is going to be stand-alone project so you won't use the workspace.

Final Project

In this final project, you'll build a very simple game: where you (player) fights with the boss. So here is a simple layman's explanation of the game mechanics.

Game Description

This game is a one-on-one battle between a player and a boss. To begin, the player selects their character from three options: Warrior, Mage, or Archer. Once the player's character data is stored in the program, the game begins.

In the game, the player immediately faces the boss, who starts with 10 lives (represented as an integer), while the player begins with 10 lives by default. The objective is to defeat the boss using a specific rule: the boss has weaknesses represented by letters (X, Y, Z), each associated with a random number.

During gameplay, if the player enters one of these letters, for example, 'Y' with a value of 4, and the boss starts with 0 lives, the program subtracts 4 lives from the boss, leaving 6. Similarly, when the player makes a move with a letter, the boss also makes a move with the a random letter with an associated value added to it.

The player progresses to the next level upon defeating the boss, continuing the battle with new challenges. I call this game Battle Showdown 🤣😁😂.

Battle Showdown Mechanics Summary

Player and Boss Lives

• Player starts with 10 lives.
• Boss starts with 10 lives.

Weaknesses and Values

• Boss and the player has weaknesses represented by letters ( X, Y, Z), each associated with a random number.

Gameplay

• Player inputs a letter (for example, 'Y') and the associated value (for example, 4) is subtracted from the boss's lives.
• Boss retaliates with a letter and the same value is subtracted from the player's lives.
• The objective is for the player to reduce the boss's lives to 0 to progress to the next level.

Match Equation

Let's define the key variables:

• (Lp) = Player's current lives.
• (Lb) = Boss's current lives.
• (V) = Value associated with the letter representing the attack.

Initial conditions:

• ( Lp = 10 )
• ( Lb = 10 )

Player's turn:

• Player selects a letter with an associated value (V).
• Boss's lives are reduced: (Lb = Lb - V).

Boss's retaliation:

• Boss selects a letter (same value (V)).
• Player's lives are reduced: (Lp = Lp - V).

This continues until either ( Lb ) (boss's lives) or ( Lp ) (player's lives) reaches 0.

Equations

After the player's attack and the Boss's retaliation:
[Lb = Lb - V]
[Lp = Lp - V]

The game loop continues with the player and boss exchanging moves. Repeat until Lb <= 0 or Lp <= 0

Example

If the player inputs 'Y' with a value of 4:

• Initial: ( Lp = 10 ), ( Lb = 10 )
• Player's attack: ( Lb = 10 - 4 = 6 )
• Boss's retaliation: ( Lp = 10 - 4 = 6 )

Next move:

• If the player inputs another value, let's say: 'X' with a value of 5:
• Player's attack: ( Lb = 6 - 5 = 1 )
• Boss's retaliation: ( Lp = 6 - 5 = 1 )

The player wins as the Boss's lives ( Lb ) have reached 0.

The match equation for each round of the game can be summarized as:
[Lb = Lb - V]
[Lp = Lp - V]
This process is repeated until either the player's lives (( Lp )) or the Boss's lives (( Lb )) reach 0, determining the winner of the battle.

Windows Error

If you use Windows, you may encounter an error with the link.exe. Honestly, I cannot explain the reason behind the error, but in the Gear docs, it was made clear that Windows users might experience some problems when building their project.

But rest assured, there's a solution, and I'm going to guide you through it. So please follow these steps carefully so you don't have to deal with bugs along the way.

Step 1 - Install WSL via Command Prompt

Open your CLI with administrative privileges, and run the command below:

wsl --install

After excutting the command, run the command below to list other Linux releases.

wsl -l -o

This command shows a list of other Linux distros, and you can select anyone you've used before. If you're new to Linux distros, I recommend selecting the Ubuntu-22.04.

These are just lists and are read-only. In order to select your system, run the command below.

wsl --install -d {Distribtion Name here(Ubuntu-22.04)}

After you're done with the installation, restart your PC. Wait a little while for the terminal to popup and prompt you for your details such as your username and password. If the terminal doesn't open, go to your start menu, and you will find something similar to this in your Start menu.

Ubuntu in start menu

After that, the next thing to do is to install Rust on your WSL.

How to Install Rust On Your WSL

To install Rust on your machine, I recommend that whenever you want to install any package, it is best practice to install updates and upgrades to the system before continuing with the installation.

sudo apt update && sudo apt upgrade -y

When you run sudo apt update && sudo apt upgrade -y, you first update the package lists to get the latest information about available software packages. Then, if the update is successful, it proceeds to upgrade the installed packages to their latest versions, automatically confirming the upgrades to avoid manual intervention. This is a common and recommended practice to keep your Linux system up-to-date and secure.

Essential Dependencies.

The command below installs essential development tools (build-essential, gcc, and make) and the curl utility for making HTTP requests and downloading files. These packages are commonly required for software development, compilation, and system administration tasks.

 sudo apt install curl build-essential gcc make -y

After that, run the command in the terminal

 curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

In the installation process, you'll be prompted a question: go with the default when it happens.

1. Proceed with installation (default) --> Enter
2. Customize installation
3. Cancel installation.

After this prompt, you have successfully installed Rust on the Ubuntu System. Now the next step is to restart your terminal, simply close the current terminal. Open a new one, and run the command below.

source "$HOME/.cargo/env"

What this command source "$HOME/.cargo/env" does is to activate the Rust environment. The reason is that the Rust environment comprises essential variables and configurations required for effective Rust usage. Now, once run, there's no output, so you can verify the installation by running the command below.

 rustc -V

Expected output:

rockyessel@UBUNTU-ROCKY:~$ rustc -V rustc 1.73.0 (cc66ad468 2024-02-07)

When you're done, there're also additional dependencies we have to install. So here, install them.

// Install the following.

 --> rustup toolchain add nightly-2023-09-18
 --> rustup target add wasm32-unknown-unknown --toolchain nightly-2023-09-18

After successfully installing them, head to the next section, which is building a game project.

In your WSL terminal, create your project name battle-showdown, and adding all the necessary toml files, and dependences. After that, cd into your project battle-showdown and added another program called io, this is where you write your metadate and other complex or simple data-type for your dApp.

battle-showdown
.
├── Cargo.toml
├── io
│   ├── Cargo.toml
│   └── src
│       └── lib.rs
└── src
    └── lib.rs

So head-over to to your ./io/src/lib.rs and paste the follow code:

#![no_std]

use gmeta::Metadata;

pub struct BattleShowdown;

impl Metadata for BattleShowdown {
    type Init = ();
    type Handle = ();
    type State = ();
    type Reply = ();
    type Others = ();
    type Signal = ();
}

Here, you have defined a new public struct named BattleShowdown. Structs are used to create custom data types by grouping fields of various types together. But in this case, you're providing an implementation for the required types of the Metadata trait for the BattleShowdown struct: impl Metadata for BattleShowdown.

type Init = (), type Handle = (), type State = (), type Reply = (), type Others = (), and type Signal = () specifies that the handlers or functions data type for BattleShowdown is of type (), which in Rust's unit type, equivalent to void in other language such as TypeScript.

So for now, we're saying that these handlers do not send or receive data as such. Hence, the code just specifies how BattlwShowdown interacts with the system. However, it is worth mentioning that, the BattleShowdown struct itself doesn't have any specific initialization data, state, handling behavior, replies, signals, or other associated types defined.

Building Our Game

First off, let's make register the io in your parent directory cargo.toml. So head over to ./cargo.toml and paste the code below:

workspace = { members = ["io"] }
[package]
name = "battle-showdown"
version = "0.1.0"
edition = "2021"

[dependencies]
gstd = "1.4.1"
battle-showdown-io={path = "io"}



[build-dependencies]
gear-wasm-builder = "1.4.1"
battle-showdown-io={path = "io"}

I've ensured that the "battle-showdown-io" path is included in both the dependencies and build-dependencies sections. This decision was intentional because when it's added solely to build-dependencies, only the structs, enums, and other data types or functions within the build.rs file gain access to them, not the dependencies in your ./src/lib.rs. This is important because I'll be utilizing battle-showdown-io in both build-dependencies (build.rs) and dependencies (./src/lib.rs).

This step is crucial because overlooking it can lead to frustrating import errors.

Next, is the file ./io/cargo.toml, paste the following code below.

[package]
name = "battle-showdown-io"
version = "0.1.0"
edition = "2021"

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

[dependencies]
gstd = "1.4.1"
gmeta = "1.4.1"
parity-scale-codec = { version = "3.6.12", default-features = false }
scale-info = { version = "2.11.3", default-features = false }

Explaining Metadata For BattleShown

It's crucial to pay closer attention to this section, as I'll shed more light on explaining the metadata types for BattleShown and deploying it on the Vara Network.

#![no_std]

use gmeta::Metadata;

pub struct BattleShowdown;

impl Metadata for BattleShowdown {
    type Init = ();
    type Handle = ();
    type State = ();
    type Reply = ();
    type Others = ();
    type Signal = ();
}

Defining Initialization – Init

To define the types for this purpose, consider whether your program or smart contract needs to store data or perform actions before the user can interact with it. In the case of this game, the answer is yes.

The game assumes that only one person is playing and does not allow users to create their characters or players. This means that you need to store data before proceeding to use this program, and in this scenario, we need information about the person/developer/actor/user deploying the contract or program, which is you.

Here is the information you'll want to store:

• playerId - Type: ActorId
  The playerId is actually the address associated with your account, which has the type of ActorId.
• playerName - Type: String
  This has a type of string, pretty much straightforward.
• playerCharacterType - Type: Enum
  The playerCharacterType is an enum that gives the actor an option to select which type they want to be, with options including Mage, Warrior, and Archer.

#![no_std]

use gmeta::Metadata;

pub struct BattleShowdown;

impl Metadata for BattleShowdown {
    type Init = InOut<InitBattleShowdown, String>;
    type Handle = ();
    type State = ();
    type Reply = ();
    type Others = ();
    type Signal = ();
}

#[derive(Debug, Clone, Copy, Encode, Decode, TypeInfo)]
pub enum CharacterType {
    Warrior,
    Mage,
    Archer,
}


#[derive(Default, Debug, Encode, Decode, TypeInfo)]
pub struct InitBattleShowdown {
    pub player_id: ActorId,
    pub player_character_type: CharacterType,
    pub player_name: String,
}

Although I've previously discussed metadata, you might be curious about what type Init = InOut<InitBattleShowdown, String>; means. Well, it's nothing complex. Here, we're simply stating that the init handle will accept a data type of InitBattleShowdown and will respond with a data type of String.

Before you continue, one more step remains: implementing a default trait for the enum CharacterType. This ensures that if the CharacterType is not explicitly defined, it defaults to Warrior. Simply add the following code to the existing code above:

impl Default for CharacterType {
    fn default() -> Self {
        CharacterType::Warrior
    }
}

Defining the Handle

Defining a type for the handle function mirrors the process for the init function, but the actual implementation is left to the developer, which in this case, is you. After reviewing code and experimenting with different approaches, I discovered a method used by Gear Protocol (which shares similarities with some of their projects) that made more sense.

Action & Event

In their implementation, they utilized Actions and Events. Actions represent a set of operations that the program can perform, while Events are the outcomes of these Actions.

For example, in the context of this game, you could have an action named Attack with a corresponding Event named Attacked. These could potentially accept parameters and return results.

Therefore, to define the handle type, include the following code in your existing codebase:

#[derive(Debug, Encode, Decode, TypeInfo)]
pub enum BattleShowdownAction {
    Attack {
        character_hit_power_value: PlayerHitPowerValue,
    },
}

Previously, when describing the game mechanics, I introduced a mechanic involving a letter with a randomly assigned number to inject an element of randomness. In this context, these letters correspond to an ENUM state of X, Z, and Y.

Therefore, to implement this mechanic, add the following code:

...

#[derive(Debug, Clone, Copy, Encode, Decode, TypeInfo)]
pub enum PlayerHitPowerValue {
    X,
    Y,
    Z,
}

When an actor or user decides to attack the boss, they can select from the options provided above, each with a random value. Consequently, each attack on the boss will yield different outcomes due to the variability in these values. Similar to how you implemented a default trait for the CharacterType, you should follow suit here.

impl Default for PlayerHitPowerValue {
    fn default() -> Self {
        PlayerHitPowerValue::X
    }
}

Event

As mentioned earlier, events are the outcomes of actions. Unlike the BattleShowdownAction, which only had one action, the BattleShowdownEvent will encompass more than two actions. Why? Because the game's logic dictates that when the user attacks, the boss also counterattacks. This results in three possible outcomes: either the user loses, the boss is defeated, or the battle continues.

However, the third outcome is contingent upon the first two outcomes.
Therefore, for the BattleShowdownEvent, you will need to define:

#[derive(Debug, Encode, Decode, TypeInfo)]
pub enum BattleShowdownEvent {
    Attacked {
        id: ActorId,
        character_type: CharacterType,
        name: String,
        player_lives: u32,
        boss_livesL: u32,
    },

    PlayerLost {
        id: ActorId,
        character_type: CharacterType,
        boss_livesL: u32,
        player_lives: u32,
        message: String,
    },

    BossLost {
        character_type: CharacterType,
        player_lives: u32,
        boss_livesL: u32,
        message: String,
    },
}

You have one action, but there are three possible events, correct? When the user/actor attacks the boss and the boss counterattacks, if either of them is defeated, the "Attacked" event is returned. However, if the player successfully defeats the boss, the "BossLost" event is returned.
Now that you have a solid understanding, let's incorporate both the input and output types for the Handle function: type Handle = InOut<BattleShowdownAction, BattleShowdownEvent>;.

Defining State

As previously mentioned, the state stores information within your program. For BattleShowdown, the state you'd want to store includes information about the player, the boss, and the current level.

#[derive(Default, Debug, Encode, Decode, TypeInfo)]
pub struct BattleShowdownState {
    pub player_id: ActorId,
    pub player_character_type: CharacterType,
    pub current_level: u32,
    pub player_lives: u32,
    pub player_name: String,
    pub boss_lives: u32,
    pub player_hit_power: u32,
    pub boss_hit_power: u32,
}

Therefore, whenever you call the state function, you should expect to see the result in this format. Now, add the BattleShowdownState to the state in the metadata, like so: type State = Out<BattleShowdownState>;.

With that, the setup is complete. Here is the entire code for the ./io/src/lib.rs file.

#![no_std]

use gmeta::{In, InOut, Metadata, Out};
use gstd::{prelude::*, ActorId};

// Define the main struct for the BattleShowdown
pub struct BattleShowdown;

// Implementing Metadata for BattleShowdown
impl Metadata for BattleShowdown {
    // Define the type for initialization messages
    type Init = InOut<InitBattleShowdown, String>;
    // Define the type for handle messages
    type Handle = InOut<BattleShowdownAction, BattleShowdownEvent>;
    // Define the type for state messages
    type State = Out<BattleShowdownState>;
    type Reply = ();
    type Others = ();
    type Signal = ();
}

// Struct for initializing the BattleShowdown
#[derive(Default, Debug, Encode, Decode, TypeInfo)]
pub struct InitBattleShowdown {
    pub player_id: ActorId,
    pub player_character_type: CharacterType,
    pub player_name: String,
}

// Struct representing the state of the BattleShowdown
#[derive(Default, Debug, Encode, Decode, TypeInfo)]
pub struct BattleShowdownState {
    pub player_id: ActorId,
    pub player_character_type: CharacterType,
    pub current_level: u32,
    pub player_lives: u32,
    pub player_name: String,
    pub boss_lives: u32,
    pub player_hit_power: u32,
    pub boss_hit_power: u32,
}

// Enum representing different character types
#[derive(Debug, Clone, Copy, Encode, Decode, TypeInfo)]
pub enum CharacterType {
    Warrior,
    Mage,
    Archer,
}

// Enum representing different values for player hit power
#[derive(Debug, Clone, Copy, Encode, Decode, TypeInfo)]
pub enum PlayerHitPowerValue {
    X,
    Y,
    Z,
}

// Implementing Default for PlayerHitPowerValue
impl Default for PlayerHitPowerValue {
    fn default() -> Self {
        PlayerHitPowerValue::X
    }
}

// Implementing Default for CharacterType
impl Default for CharacterType {
    fn default() -> Self {
        CharacterType::Warrior
    }
}

// Enum representing different actions in the BattleShowdown
#[derive(Debug, Encode, Decode, TypeInfo)]
pub enum BattleShowdownAction {
    Attack {
        character_hit_power_value: PlayerHitPowerValue,
    },
}

// Enum representing different events in the BattleShowdown
#[derive(Debug, Encode, Decode, TypeInfo)]
pub enum BattleShowdownEvent {
    Attacked {
        id: ActorId,
        character_type: CharacterType,
        name: String,
        player_lives: u32,
        boss_lives: u32,
    },
    PlayerLost {
        id: ActorId,
        character_type: CharacterType,
        boss_lives: u32,
        player_lives: u32,
        message: String,
    },
    BossLost {
        character_type: CharacterType,
        player_lives: u32,
        boss_lives: u32,
        message: String,
    },
}

Build.rs

Import BattleShowdown to the build.rs from your parent directory at ./src/build.rs. If you encounter an import error, make sure that in your ./cargo.toml, you're registering battle-showdown-io={path = "io"} there.

use battle_showdown_io::BattleShowdown;

fn main() {
    gear_wasm_builder::build_with_metadata::<BattleShowdown>();
}

That's it for the build.rs, and what it does is to build your project into wasm and then build the metadata for BattleShown for you.

Game Logic Implementation - ./src/lib.rs

For this section, I'll write the code below, then I'll explain this as we go. There's going to be a problem I'd want you to solve, which will be about the state.

#![no_std]

use gstd::{exec, msg, prelude::*, ActorId};

use battle_showdown_io::*;

// Function to generate random number between 1 and 3
fn get_random_u32() -> u32 {
    let salt = msg::id();
    let (hash, _num) = exec::random(salt.into()).expect("get_random_u32(): random call failed");
    (u32::from_le_bytes([hash[0], hash[1], hash[2], hash[3]]) % 3) + 1 // Generate random number between 1 and 3
}

#[derive(Debug, Default)]
pub struct BattleShowdown {
    pub player_id: ActorId,
    pub player_character_type: CharacterType,
    pub current_level: u32,
    pub player_lives: u32,
    pub player_name: String,
    pub boss_lives: u32,
    pub character_hit_power_value: PlayerHitPowerValue,
    pub player_hit_power: u32,
    pub boss_hit_power: u32,
    pub game_state: String,
}

static mut BATTLESHOWNDOWN: Option<BattleShowdown> = None;

#[no_mangle]
unsafe extern "C" fn init() {
    let init: InitBattleShowdown = msg::load().expect("Unable to decode InitBattleShowdown");

    let battle_showdown = BattleShowdown {
        player_id: msg::source(),
        player_character_type: init.player_character_type,
        player_name: init.player_name,
        boss_lives: 10,
        player_lives: 10,
        ..Default::default()
    };

    BATTLESHOWNDOWN = Some(battle_showdown);

    msg::reply_bytes("Successfully initialized", 0).expect("Failed to initialize successfully.");
}

impl Encode for BattleShowdown {
    fn encode(&self) -> Vec<u8> {
        let mut encoded = Vec::new();

        // Encode each field of BattleShowdown struct
        encoded.extend_from_slice(&self.player_id.encode());
        encoded.extend_from_slice(&self.player_character_type.encode());
        encoded.extend_from_slice(&self.current_level.encode());
        encoded.extend_from_slice(&self.player_lives.encode());
        encoded.extend_from_slice(&self.player_name.encode());
        encoded.extend_from_slice(&self.boss_lives.encode());
        encoded.extend_from_slice(&self.character_hit_power_value.encode());
        encoded.extend_from_slice(&self.player_hit_power.encode());
        encoded.extend_from_slice(&self.boss_hit_power.encode());
        encoded.extend_from_slice(&self.game_state.encode());

        encoded
    }
}

impl BattleShowdown {
    // Placeholder for the `attack` method
    fn attack(&mut self, _character_hit_power_value: PlayerHitPowerValue) -> BattleShowdownEvent {
        // Implement this method according to your game logic
        // For now, just returning an empty event

        // Calculate total hit power for player based on character type and random values
        let character_hit_power = match &self.player_character_type {
            CharacterType::Warrior => 4,
            CharacterType::Mage => 3,
            CharacterType::Archer => 2,
        };

        let player_hit_power = match &self.character_hit_power_value {
            PlayerHitPowerValue::X => character_hit_power + get_random_u32(),
            PlayerHitPowerValue::Y => character_hit_power + get_random_u32(),
            PlayerHitPowerValue::Z => character_hit_power + get_random_u32(),
        };

        // Placeholder for boss attack logic
        // Update boss hit power to a random value for each attack
        self.boss_hit_power = get_random_u32();

        self.player_hit_power = player_hit_power;

        // Reduce boss's lives based on player's hit power
        self.boss_lives = self.boss_lives.saturating_sub(self.player_hit_power);
        // Reduce player's lives based on boss's hit power
        self.player_lives = self.player_lives.saturating_sub(self.boss_hit_power);

        // Check if player or boss has lost
        if self.player_lives == 0 {
            // Player lost
            self.game_state = "Player lost.".to_string();
            return BattleShowdownEvent::PlayerLost {
                id: self.player_id,
                boss_lives: self.boss_lives,
                character_type: self.player_character_type,
                message: "".to_string(),
                player_lives: self.player_lives,
            };
        } else if self.boss_lives == 0 {
            // Boss lost
            self.game_state = "Boss lost.".to_string();
            return BattleShowdownEvent::BossLost {
                boss_lives: self.boss_lives,
                character_type: self.player_character_type,
                player_lives: self.player_lives,
                message: "You've defeated the boos".to_string(),
            };
        }

        self.game_state = "The games continues.".to_string();
        BattleShowdownEvent::Attacked {
            boss_lives: self.boss_lives,
            character_type: self.player_character_type,
            id: self.player_id,
            name: self.player_name.clone(),
            player_lives: self.player_lives,
        }
    }
}

#[no_mangle]
extern "C" fn handle() {
    let battle_showdown_action: BattleShowdownAction =
        msg::load().expect("Could not load BattleShowdownAction");
    let battle_showdown = unsafe {
        BATTLESHOWNDOWN
            .as_mut()
            .expect("`BattleShowdown` is not initialized.")
    };
    let result: BattleShowdownEvent = match battle_showdown_action {
        BattleShowdownAction::Attack {
            character_hit_power_value,
        } => battle_showdown.attack(character_hit_power_value),
    };
    msg::reply_bytes(result.encode(), 0)
        .expect("Failed to encode or reply with `BattleShowdownEvent`.");
}

#[no_mangle]
extern "C" fn state() {
    let battle_showdown = unsafe {
        BATTLESHOWNDOWN
            .take()
            .expect("Unexpected error in taking state")
    };

    msg::reply(battle_showdown, 0).expect("Unable to share the state");
}

At first glance this might seem a lot, but it isn't, so don't get too intimidated. Before you start, make sure you understand the whole logic of the game description I gave earlier since you'll be implementing it here.

Above, we have some important functions, struct, and impl, and here is an overview of what they do.

1. With the get_random_u32 function, we generated a random number between 1 and 3.
2. The BattleShowdown struct in the /src/lib.rs represents the main state of the game. It holds information such as player and boss stats, current game level, and game state. The static mut BATTLESHOWNDOWN: Option<BattleShowdown> = None; is a static mutable variable that holds the current state of the game. It's wrapped in an Option to indicate whether the game has been initialized yet or not, which you'll use later in your implementation.
3. unsafe extern "C" fn init() is responsible for initializing the game state when called after the contract has been uploaded. It loads an initialization message, constructs a BattleShowdown instance based on that message, and sets BATTLESHOWNDOWN to Some with the constructed instance.
4. impl Encode for BattleShowdown: this trait is implemented for BattleShowdown, enabling it to be encoded into a byte representation. This is useful for serialization and sending the game state over the network. And there's a way to also implement the trait without creating an impl for BattleShowdown.
5. impl BattleShowdown: this impl for BattleShowdown is where the entire logic happens, and for now, we've only added an attack method for it. It worth noting that we'll be adding more as we continue this project.
6. So what does the attack method do? Well, The attack method simulates a combat encounter between the player and the boss character in our game. It calculates the hit power for both entities based on character type and randomness, manages their health points accordingly, and generates game events to reflect the outcome of the encounter.
7. extern "C" fn handle(): In our case, the handle function is used to process incoming messages, specifically BattleShowdownAction. So depending on the action perform by the actor, it dispatches a result of the action to the appropriate methods of BattleShowdown, such as attack, and sends back the resulting game events to the actor. Like disccued in the illustration.
8. And lastly, extern "C" fn state() simply retrieves the current game state represented by BattleShowdown and sends it as a reply.

This is the overall explanation to the code in the file. But leaving with this isn't enough for even me. Let's disccus more below.

Understanding theinit()

#[derive(Debug, Default)]
pub struct BattleShowdown {
    pub player_id: ActorId,
    pub player_character_type: CharacterType,
    pub current_level: u32,
    pub player_lives: u32,
    pub player_name: String,
    pub boss_lives: u32,
    pub character_hit_power_value: PlayerHitPowerValue,
    pub player_hit_power: u32,
    pub boss_hit_power: u32,
    pub game_state: String,
}

static mut BATTLESHOWNDOWN: Option<BattleShowdown> = None;

#[no_mangle]
unsafe extern "C" fn init() {
    // Load initialization data
    let init: InitBattleShowdown = msg::load().expect("Unable to decode InitBattleShowdown");

    // Create a BattleShowdown instance with initial values
    let battle_showdown = BattleShowdown {
        player_id: msg::source(),
        player_character_type: init.player_character_type,
        player_name: init.player_name,
        boss_lives: 10,
        player_lives: 10,
        ..Default::default()
    };

    // Store the BattleShowdown instance
    BATTLESHOWNDOWN = Some(battle_showdown);

    // Reply to signal successful initialization
    msg::reply_bytes("Successfully initialized", 0).expect("Failed to initialize successfully.");
}

The function loads data from an initialization message (InitBattleShowdown) sent by the developer or player. This data includes the player's chosen character type and name. Based on the initialization data, a BattleShowdown instance is created with initial values, which is stored in battle_showdown.

This instance represents the state of the game, including player and boss stats, current level, and game state. The created BattleShowdown instance is stored in the BATTLESHOWNDOWN static variable, allowing the game logic to access and manipulate the game state throughout the gameplay. Finally, a reply message is sent back to the developer or player to indicate successful initialization of the game contract.

This function sets up the initial state of the game, paving the way for further interactions and gameplay logic.

Understanding the handle()

#[no_mangle]
extern "C" fn handle() {
    // Load the action from the message
    let battle_showdown_action: BattleShowdownAction =
        msg::load().expect("Could not load BattleShowdownAction");

    // Retrieve the current game state
    let battle_showdown = unsafe {
        BATTLESHOWNDOWN
            .as_mut()
            .expect("`BattleShowdown` is not initialized.")
    };

    // Execute the appropriate action on the game state and get the result
    let result: BattleShowdownEvent = match battle_showdown_action {
        BattleShowdownAction::Attack {
            character_hit_power_value,
        } => battle_showdown.attack(character_hit_power_value),
    };

    // Send back the result as a reply message
    msg::reply_bytes(result.encode(), 0)
        .expect("Failed to encode or reply with `BattleShowdownEvent`.");
}

The handle() function plays a crucial role in processing incoming messages and orchestrating the game's actions. It serves as the bridge between player interactions and the game's internal logic. When invoked, handle() begins by loading the action sent by the player from the message.

This action, encapsulated as BattleShowdownAction, dictates the player's intended move, such as attacking the boss. Next, the function retrieves the current game state from the BATTLESHOWNDOWN variable. This state holds essential information about the player, the boss, and the overall game environment.

With both the action and the game state at hand, handle() proceeds to execute the appropriate action. For instance, if the player's action is an attack, the function triggers the attack() method on the battle_showdown instance. This method calculates the outcome of the player's attack, considering factors like the player's hit power and the boss's remaining health points.

Crucially, the attack() method requires a parameter: character_hit_power_value. This parameter corresponds to the player's choice between three options: X, Y, and Z, each associated with different hit power values as disccused in earlier sections.

Once the action is executed, handle() generates an event, encapsulated as BattleShowdownEvent, reflecting the outcome of the player's move. This event encapsulates important details, such as changes in player and boss health points. Finally, handle() responds to the player by replying with the result of the action as a byte-encoded message. This message contains the updated game state, allowing the player to understand their current situation, including their health status and that of the boss.

Understanding the impl BattleShowdown for attack

impl BattleShowdown {
    fn attack(&mut self, _character_hit_power_value: PlayerHitPowerValue) -> BattleShowdownEvent {
        // Calculate total hit power for player based on character type and random values
        let character_hit_power = match &self.player_character_type {
            CharacterType::Warrior => 4,
            CharacterType::Mage => 3,
            CharacterType::Archer => 2,
        };

        let player_hit_power = match &self.character_hit_power_value {
            PlayerHitPowerValue::X => character_hit_power + get_random_u32(),
            PlayerHitPowerValue::Y => character_hit_power + get_random_u32(),
            PlayerHitPowerValue::Z => character_hit_power + get_random_u32(),
        };

        // Placeholder for boss attack logic
        // Update boss hit power to a random value for each attack
        self.boss_hit_power = get_random_u32();

        self.player_hit_power = player_hit_power;

        // Reduce boss's lives based on player's hit power
        self.boss_lives = self.boss_lives.saturating_sub(self.player_hit_power);
        // Reduce player's lives based on boss's hit power
        self.player_lives = self.player_lives.saturating_sub(self.boss_hit_power);

        // Check if player or boss has lost
        if self.player_lives == 0 {
            // Player lost
            self.game_state = "Player lost.".to_string();
            return BattleShowdownEvent::PlayerLost {
                id: self.player_id,
                boss_lives: self.boss_lives,
                character_type: self.player_character_type,
                message: "".to_string(),
                player_lives: self.player_lives,
            };
        } else if self.boss_lives == 0 {
            // Boss lost
            self.game_state = "Boss lost.".to_string();
            return BattleShowdownEvent::BossLost {
                boss_lives: self.boss_lives,
                character_type: self.player_character_type,
                player_lives: self.player_lives,
                message: "You've defeated the boss".to_string(),
            };
        }

        self.game_state = "The game continues.".to_string();
        // Return event indicating attack occurred
        BattleShowdownEvent::Attacked {
            boss_lives: self.boss_lives,
            character_type: self.player_character_type,
            id: self.player_id,
            name: self.player_name.clone(),
            player_lives: self.player_lives,
        }
    }
}

The attack method within the BattleShowdown implementation simulates a pivotal moment in the game: a combat encounter between the player and the boss character.

Here's how it works:

Firstly, the method calculates the total hit power for the player based on their character type (character_hit_power) and randomness (player_hit_power). Different character types (Warrior, Mage, or Archer) have different base hit powers.

Next, a random hit power value is added to the character's base hit power. This adds an element of unpredictability to each attack. The method then updates the boss's hit power (self.boss_hit_power = get_random_u32();) to a random value, representing the boss's retaliatory strike against the player.

After calculating the hit powers, the method reduces the boss's lives based on the player's hit power and vice versa, updating their respective health points accordingly.

        // Reduce boss's lives based on player's hit power
        self.boss_lives = self.boss_lives.saturating_sub(self.player_hit_power);
        // Reduce player's lives based on boss's hit power
        self.player_lives = self.player_lives.saturating_sub(self.boss_hit_power);

The game state is then checked to determine if either the player or the boss has lost the battle. If the player's health points reaches zero, the game state is updated to indicate that the player has lost. Conversely, if the boss's health points reach zero, the game state reflects the boss's defeat.

        // Check if player or boss has lost
        if self.player_lives == 0 {
            // Player lost
            self.game_state = "Player lost.".to_string();
            return BattleShowdownEvent::PlayerLost {
                id: self.player_id,
                boss_lives: self.boss_lives,
                character_type: self.player_character_type,
                message: "".to_string(),
                player_lives: self.player_lives,
            };
        } else if self.boss_lives == 0 {
            // Boss lost
            self.game_state = "Boss lost.".to_string();
            return BattleShowdownEvent::BossLost {
                boss_lives: self.boss_lives,
                character_type: self.player_character_type,
                player_lives: self.player_lives,
                message: "You've defeated the boss".to_string(),
            };
        }

        self.game_state = "The game continues.".to_string();
        // Return event indicating attack occurred
        BattleShowdownEvent::Attacked {
            boss_lives: self.boss_lives,
            character_type: self.player_character_type,
            id: self.player_id,
            name: self.player_name.clone(),
            player_lives: self.player_lives,
        }

Finally, if neither the player nor the boss has lost, the game state is updated to indicate that the battle continues.

Understanding the State()

#[no_mangle]
extern "C" fn state() {
    let battle_showdown = unsafe {
        BATTLESHOWNDOWN
            .take()
            .expect("Unexpected error in taking state")
    };

    msg::reply(battle_showdown, 0).expect("Unable to share the state");
}

For this instance there's nothing more to share, it retrieves the current state of the game, represented by the BattleShowdown struct, from a static mutable variable BATTLESHOWNDOWN, and sends a reply message containing the game state back to the player. If there is an error sending the reply message, it will panic with an error message indicating the inability to share the state.

And that's that for this project. There are some exciting features you can consider if you want to extend this project. Imagine the possibility of resetting the game state, accommodating multiple players, or even resetting the game for a single player. And for the ambitious, you could even tackle the challenge of resetting the state for the entire game. These additions can offer new dimensions to the project and provide excellent opportunities for you to challenge yourself.

Short Recording of what we've built - Demo

In the video you could see I added another method for resetting everything back to it inital state. Though I didn't guide you through the process of doing that, you should know it is easy to implement, and I've added a GitHub repository for the entire code.

Conclusion

As demonstrated, developing a smart contract with Gear Protocol becomes straightforward once you grasp the communication message concepts. By following the steps outlined, you can start building your own projects with confidence.

While this article didn't delve into handling transactions such as token transfers, minting, or NFTs, I will cover these topics in a future article.

For now, you can explore the repository of the project we built together: Battle-Showdown, and if you have any question to ask, feel free to reach @rockyessel on X.

We just posted a comprehensive 12-hour course on the freeCodeCamp.org YouTube channel that is designed to provide an introduction to blockchain technology with a focus on the Tezos ecosystem. It covers everything from the basics of blockchain technology to more advanced topics such as smart contract development and dApp deployment. The only perquisites are a basic understanding of Python. This course was made possible by a grant from Tezos Foundation back in 2022.

What Makes Tezos Unique?

Tezos supports smart contracts and provides a robust platform for developing decentralized applications (dApps), making it a strong competitor in a landscape dominated by other players like Ethereum. One of the key features of Tezos is its on-chain governance process, where proposed amendments to the protocol can be submitted by developers and voted on by token holders. This democratic approach ensures that the future direction of the network reflects the preferences of its community, helping to prevent contentious forks and ensuring a stable and predictable evolution of the platform.

Course Overview

Here are some of the key sections included in this massive course:

• Introduction to Blockchain and Tezos: Understand the fundamental concepts of blockchain technology and how Tezos differentiates itself from other blockchain platforms.

• Setting Up a Tezos Wallet: Learn about the different types of wallets available for Tezos, how to set them up, and how to secure your assets.

• Smart Contracts on Tezos: Dive deep into writing and deploying smart contracts. Explore the Tezos-specific languages like Michelson and SmartPy, and learn how to use them to create functional and secure contracts.

• Developing Decentralized Applications: Gain hands-on experience developing dApps on Tezos, understanding the architecture, and connecting the frontend with the Tezos blockchain backend.

• Governance and Upgrades: Learn about the governance process that allows Tezos to evolve smoothly over time, and how you can participate in this process as a developer or a stakeholder.

This course will help you deepen your understanding of blockchain technology and develop the skills necessary to build innovative solutions on Tezos. With its hands-on approach, the course not only teaches theoretical knowledge but also provides practical skills and real-world applications. By the end of this course, you will be proficient in navigating the Tezos ecosystem, developing your own smart contracts, and contributing to the platform’s evolution.

Watch the full course on the freeCodeCamp.org YouTube channel (12-hour watch).

Ethereum is one of the major pioneers in the decentralized ecosystem. And Web3.js is an essential tool if you're working on Ethereum-based projects.

To fully understand why this tool is important, we must first take a deeper dive into Ethereum development.

Grab your coffee, young Web3 enthusiast. We're going on a journey that will change your Web3 career forever.

Prerequisites

Before you can carry on with this tutorial, you'll need to understand the basics of JavaScript, and should be able to install npm packages.

If you've worked with JavaScript before, the rest of this tutorial should be a breeze.

What is Ethereum Development?

Ethereum is a decentralized open-source blockchain platform that lets developers build decentralized applications, popularly known as dAPPs. These dApps are built on top of the Ethereum blockchain, harnessing some of the core features of the Ethereum network.

Ethereum is written in Solidity, which is the primary programming language used in the Ethereum ecosystem. You can use Solidity to design smart contracts, which are basically self-executing contracts that power a lot of dApps.

If you want to work in Ethereum development, understanding smart contracts is extremely important.

Smart contracts consist of the terms of the agreement between buyer and seller that are directly written into the lines of code. This code is written in Solidity, which can only exist in the blockchain network.

To become an Ethereum developer, you are going to work mainly around the network, building smart contracts and dApps.

Let's talk about the tools you are going to need:

• Solidity
• Ether.js
• JavaScript/React for front-end visual interaction

The World of Web3.js

Now that you have an idea of what Ethereum development is, we can begin to understand Web3.js a little better.

Web3.js is a collection of libraries that allow you to interact with a local or remote Ethereum node, using HTTP, IPC, or Web Sockets (which is my personal favorite). It is written in JavaScript, and to put it simply, it lets you interact with the blockchain more efficiently.

By reading data from the blockchain, you will be able to make transactions and deploy smart contracts live on the mainnet.

How to Set Up Web3.js

Web3.js can access blockchain information from both the back end and front end to make transactions and deploy smart contracts.

You are going to need Node.js, which you can easily download from the official website. The installation process is pretty straightforward.

After you've successfully installed Node and npm (the official package manager for Node), open your command line in the root folder of your project and type the following command:

npm install web3 --save

Then you'll be able to import Web3.js into a Node script using this simple code:

const Web3 = require("web3")

We've got some of the hard part locked down. Now we just need our project to communicate directly with the blockchain.

To initiate our Web3 provider, we must instantiate, which just means creating a Web3 instance, and pass a constructor to the URL of the provider.

In this case, we'll have to find an Ethereum node that we can connect to and start crafting magic.

There are multiple node providers like Alchemy, Chainstack, and Moralis, and there's a lot of documentation when it comes to getting a direct access.

You can make use of the Ganache instance as well, which will essentially help you set up the environment for anything you need to work in your local environment.

To understand how to set up Ganache, you can read the linked guide that covers everything you need to know.

You simply place this below your code like so:

const Web3 = require("web3")
const web3 = new Web3("http://localhost:8545")

To test that you have successfully configured everything, you can write some simple code to get the latest block number on the blockchain:

var Web3 = require("web3")
const web3 = new Web3("http://localhost:8545"")

web3.eth.getBlockNumber(function (error, result) {
  console.log(result)
})

This function simply accepts a callback as a parameter, then prints the result as an integer. Running this would just give you a block number on your console.

There are many other functions you can use. The web3 official documentation provides a comprehensive list of functions that you can learn about and try out.

Conclusion

If you're wanting to get into Ethereum development, Web3.js will be a vital part of your stack. Throughout your journey, you are going to be interacting with the Ethereum node more frequently and Web3.js will come in handy.

There are other alternatives like Ether.js, which also strive to provide a complete library that can interact with the Ethereum node. But Web3 is known to have a larger network of support, a larger community of developers, and more mature documentation that you can refer to regarding problems of any sort.

Hopefully this article has given all of the insights you need for you to start your Ethereum journey. I'm available on Twitter, if you have any questions.

This curriculum is made possible by The Solana Foundation, who gave our charity a grant to 100% fund development of this curriculum.

What will this curriculum teach you?

The Solana curriculum contains ten interactive practice projects that will guide you through learning the Solana protocol and their tools.

Through these projects, you will learn how to build and deploy smart contracts, dApps, work with their command line tools, and much more.

There are also five challenging integrated projects to test your knowledge.

How does it work?

The courses will run in a docker container using VS Code and the freeCodeCamp Courses extension.

Here's a Sample

Which Projects Will You Build as Part of the Solana Curriculum?

These projects consist of two interactive practice projects and one integrated project. Here are the projects:

1. Learn How to Set Up Solana by Building a Hello World Smart Contract
2. Learn How to Interact with On-Chain Programs
3. Build a Smart Contract
4. Learn Solana's Token Program by Minting a Fungible Token
5. Learn the Metaplex SDK by Minting an NFT
6. Build a University Certification NFT
7. Learn Anchor by Building Tic-Tac-Toe: Part 1
8. Learn Anchor by Building Tic-Tac-Toe: Part 2
9. Build an Anchor Leaderboard
10. Learn How to Build a Client-Side App: Part 1
11. Learn How to Build a Client-Side App: Part 2
12. Build a Client-Side App
13. Learn How to Build for Mainnet
14. Learn How to Deploy to Devnet
15. Build and Deploy Your Freeform App

How to Run the Courses

Follow the steps below to run the courses

Developer Environment Prerequisites

Before you get started, make sure you have these installed on your computer:

1. Docker Engine
2. VS Code and the Dev Containers extension
3. Git

How to Run the Curriculum in Docker

Follow these instructions to clone the repo and run the courses:

1. Open a terminal and clone the solana-curriculum repo with:

   git clone https://github.com/freeCodeCamp/solana-curriculum.git
   

2. Navigate to the solana-curriculum directory, and open it in a VSCode workspace with:

   code .
   

3. Press Ctrl / Cmd + Shift + P to open the command palette, and run Dev Containers: Rebuild Container and Reopen in Container. VS Code will build the container to run the projects in, it will take a few minutes the first time.

4. Once it's finished, press Ctrl / Cmd + Shift + P again and run freeCodeCamp: Run Course to start the courses. This will also take a moment.
5. The simple browser will open when it's done. If it's a blank white page, use the refresh button to update it and see the courses home page.
6. Click on one of the available projects to start a project.
7. Follow the instructions to complete the project.
8. Have fun!

If you want to switch projects, click the freeCodeCamp logo at the top to get back to the home page.

freeCodeCamp Also Offers a More General Web3 Course that Covers Blockchain Fundamentals

While you are waiting for these courses, you can try the Web3 curriculum which is now in open beta. It will teach you many Web3 and blockchain concepts you will want to know for the Solana curriculum.

Where you can Learn more about the Solana Foundation

You can learn more about The Solana Foundation on their website.

But this implies that you have no control over the information relating to your identification, who has access to personally identifiable information (PII), and to what extent.

As a result, Decentralized Identity provides identity-related information that is self-controlled, private, and portable. Decentralized identifiers and attestations serve as the main building pieces.

Thanks to Ceramic's decentralized application databases, application developers can reuse data across applications and automatically make them interoperable.

In this article, you will learn about Decentralized Identity, Decentralized Identifiers, Ceramic network, and how to build a decentralized identity profile with Ethereum on Ceramic Networks.

Here's what we'll cover:

• What is a Decentralized Identity?
• What are Decentralized Identifiers?
• What is Ceramic Data Network?
• Why Ceramic Network?
• How to Build a Decentralized Identity Profile with Next.js
• Prerequisites
• Project Setup and Installation
• Install TailwindCSS in Next.js
• Authenticate Users
• Create/Update User Profile
• How to Test the Application
• Conclusion
• References

What is a Decentralized Identity?

Decentralized Identity is a digital identification concept where people, companies, and items are in charge of their data and can share it selectively without relying on a centralized authority.

This is made possible by using decentralized technologies, such as blockchain. These give people control and ownership over the information associated with their identities rather than having it stored on a central server or managed by a third party.

A decentralized identity is a self-owned, independent identity that enables trusted data exchange.

Blockchain-based digital wallets, such as those used to store and handle cryptocurrencies, serve as a practical illustration of decentralized identification. Users of these wallets control the private keys that provide them access to their money and can distribute their public keys to others to accept payments from them.

Users who manage their private keys can conduct transactions with others without relying on a central authority, such as a bank, and keep custody of their money.

What are Decentralized Identifiers?

Decentralized identifiers (DIDs) are issued, held, and controlled by individuals. Since they are kept on peer-to-peer networks or distributed ledgers (blockchains), they are globally unique, highly available, and cryptographically verifiable.

Decentralized identifiers can be associated with individuals, groups, or governmental entities.

DIDs are a vital component of the developing decentralized identity ecosystem. They are designed to offer a uniform process for developing, maintaining, and exchanging digital identities unaffiliated with any one company or piece of technology.

This implies that a DID can be maintained and controlled by the person or entity to which it belongs and utilized across various systems and applications.

In recent years, smart contract platforms like Ethereum have demonstrated the utility of decentralized applications (dApps) that can be assembled like blocks to create new applications. This is especially evident in tokens that build upon one another, in DeFi protocols that use one another, and so on.

Thanks to Ceramic, data on the internet can now have the same kind of composability. Any data type, including profiles, social connections, blog posts, identities, reputations, and so on., can be included. You will learn more about Ceramic Network in the section below.

What is Ceramic Network?

Ceramic is a public, permissionless, open-source protocol that offers computation, state transitions, and consensus for all data structures on the decentralized web.

With the help of stream processing provided by Ceramic, developers can build apps that are strong, safe, trustless, and censorship-resistant using dynamic information – without using unreliable database servers.

Ceramic stores all content in smart documents, which are append-only IPFS logs. Before being anchored in a blockchain for consensus, each commit is verified by a decentralized identification (DID).

All papers in Ceramic are openly discoverable and can be referenced by other documents or queried by any other network user because the system is entirely peer-to-peer.

Why Ceramic Network?

Data interoperability is one of Ceramic Network's key benefits. This platform features a flexible and modular data schema that enables the decentralized and interoperable sharing and combining of various sorts of data.

Developers now have an easier time creating decentralized identification solutions that can be integrated with other programs and systems.

The infrastructure of Ceramic Network is scalable, fault-tolerant, decentralized, and highly available. This enables developers to create robust decentralized identity systems available to users everywhere.

Ceramic Network also provides a set of developer tools and libraries, making it simple to create decentralized identity apps and services. These tools include SDKs, APIs, developer guides, and an expanding ecosystem of open-source tools and libraries.

Now that you have learnt the theories behind decentralized identity, let's take a practical deep dive and get your hands dirty.

How to Build a Decentralized Identity Profile with Next.js

Prerequisites

To go through this tutorial, you'll need some experience with JavaScript and React.js. Experience with Next.js isn't a requirement, but it's nice to have.

Make sure to have Node.js or npm installed on your computer. If you don't, click here.

Also, it'll be very useful to have a basic understanding of blockchain technology and Web3 concepts.

Project Setup and Installation

Navigate to the terminal and cd into any directory of your choice. Then run the following commands:

mkdir decentralized-identity-project
cd decentralized-identity-project
npx create-next-app@latest .

Accept the following options:

Install the @self.id/react and @self.id/web packages using the code snippet below:

npm install @self.id/web @self.id/react

Next, start the app using the following command:

npm run dev

You should have something similar to what is shown below: the default boilerplate layout for Next.js 13.

Install TailwindCSS in Next.js

In this section, you will set up Tailwind CSS in a Next.js project. Install tailwindcss and its peer dependencies via npm, and then run the init command to generate both tailwind.config.js and postcss.config.js.

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

Navigate to the tailwind.config.js file, and add the paths to your template files with the following code snippet.

/** @type {import('tailwindcss').Config} */

module.exports = {
  content: [
    "./app/**/*.{js,ts,jsx,tsx}",
    "./pages/**/*.{js,ts,jsx,tsx}",
    "./components/**/*.{js,ts,jsx,tsx}",

    // Or if using `src` directory:
    "./src/**/*.{js,ts,jsx,tsx}",
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

Delete all the CSS styles inside globals.css . Add the @tailwind directives for each of Tailwind’s layers to your globals.css file.

@tailwind base;
@tailwind components;
@tailwind utilities;

Configure the Provider Component

The Provider component must be placed at the top of the application tree to use the hooks detailed below. You can use it to supply an initial state as well as a specific configuration for the Self.ID clients and queries.

Update the _app.js file under the pages folder with the following code snippet:

// Import the Provider component from the "@self.id/react" library.
import { Provider } from "@self.id/react";

// Import the "globals.css" file from the "@/styles" directory.
import "@/styles/globals.css";

// Define the App component as a default export.
export default function App({ Component, pageProps }) {

  // Render the Provider component, which provides authentication and authorization functionality to the application.
  // Pass a client prop to the Provider component, which configures the Ceramic testnet with the "testnet-clay" value.
  // Render the Component with its props inside the Provider component, which allows the application to access the authentication and authorization context.

  return (
    <Provider client={{ ceramic: "testnet-clay" }}>
      <Component {...pageProps} />
    </Provider>
  );
}

In the code snippet above, we:

• Imported a context provider component and global CSS styles and then defined an App component that wraps the entire application with the context provider.
• Configured the context provider with a Ceramic testnet client, which allows the application to access authentication and authorization functionality.
• Finally, the Component is rendered with its props inside the context provider, allowing the application to access the authentication and authorization context.

Build the Layout

Next, navigate to the index.js file under the pages folder and update it with the following code:

// Import the Head component from the "next/head" module.
import Head from "next/head";

// Import the useViewerConnection and useViewerRecord hooks from the "@self.id/react" library.
import { useViewerConnection, useViewerRecord } from "@self.id/react";

// Import the EthereumAuthProvider component from the "@self.id/web" library.
import { EthereumAuthProvider } from "@self.id/web";

// Import the useState hook from the "react" module.
import { useEffect, useState } from "react";


export default function Home() {

  return (
    <>
      <Head>
        <title>
          Decentralized Identity: Build a Profile with NextJs, Ethereum & Ceramic Network
        </title>
        <meta name="description" content="Generated by create next app" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <link rel="icon" href="/favicon.ico" />
      </Head>
      <main className="min-h-screen bg-gray-200">
        <div className="bg-gray-600 py-4 px-4 sm:px-6 lg:px-8 lg:py-6 shadow-lg text-white">
          <div className="container mx-auto px-6 md:px-0">
            <h1 className="text-2xl font-bold text-white text-center">
              Decentralized Identity: Build a Profile with NextJs, Ethereum & Ceramic Network
            </h1>
          </div>
        </div>

        <div className="flex items-center justify-center pt-20 font-sans overflow-hidden">
          <div className="max-w-md w-full mx-auto">
            <div className="bg-white p-10 rounded-lg shadow-lg">
              <form>
                <div className="mb-6">
                  <label
                    className="block text-gray-700 font-bold mb-2"
                    htmlFor="name"
                  >
                    Name
                  </label>
                  <input
                    className="border border-gray-300 p-2 w-full rounded-lg"
                    type="text"
                    name="name"
                    id="name"
                    placeholder="Your name"
                  />
                </div>
                <div className="mb-6">
                  <label
                    className="block text-gray-700 font-bold mb-2"
                    htmlFor="bio"
                  >
                    Bio
                  </label>
                  <textarea
                    className="border border-gray-300 p-2 w-full rounded-lg"
                    name="bio"
                    id="bio"
                    rows="5"
                    placeholder="Write something about yourself"
                  ></textarea>
                </div>
                <div className="mb-6">
                  <label
                    className="block text-gray-700 font-bold mb-2"
                    htmlFor="username"
                  >
                    Username
                  </label>
                  <input
                    className="border border-gray-300 p-2 w-full rounded-lg"
                    type="text"
                    name="username"
                    id="username"
                    placeholder="Your username"
                  />
                </div>
                <div className="flex items-center justify-between">
                  <button
                    className="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded"
                    type="submit"
                  >
                    Update Profile
                  </button>
                  <button
                    className="bg-green-500 hover:bg-green-700 text-white font-bold py-2 px-4 rounded"
                    type="button"
                  >
                    Connect Wallet
                  </button>
                </div>
              </form>
            </div>
          </div>
        </div>
      </main>
    </>
  );
}

To start the application, run the following command and navigate to localhost:3000 on your browser; you should have something similar to what is shown below:

How to Authenticate Users

In this section, you will implement user authentication to allow users to connect their wallets and interact with the application.

Update the index.js with the following code:

//..

export default function Home() {

  // State variables for connection, connect function, and disconnect function
  const [connection, connect, disconnect] = useViewerConnection();


  const [isWindow, setIsWindow] = useState(null);


  // State variable for viewer's basic profile data
  const record = useViewerRecord("basicProfile");

  // Function to create EthereumAuthProvider using window.ethereum provider
  async function createAuthProvider() {
    const addresses = await window.ethereum.request({
      method: "eth_requestAccounts",
    });
    return new EthereumAuthProvider(window.ethereum, addresses[0]);
  }

  // Function to connect to viewer's account using created authProvider
  async function connectAccount() {
    const authProvider = await createAuthProvider();
    await connect(authProvider);
  }

  // Rendered JSX code
  return (
    <>
      {/* ... */}
      <div className="flex items-center justify-between">
        {/* ... */}

        {/* Conditionally render a button to connect/disconnect user */}
        {connection.status === "connected" ? (
          <button
            className="bg-red-500 hover:bg-red-700 text-white font-bold py-2 px-4 rounded"
            type="button"
            onClick={() => disconnect()}
          >
            Disconnect
          </button>
        ) : isWindow && "ethereum" in window ? (
          <button
            className="bg-green-500 hover:bg-green-700 text-white font-bold py-2 px-4 rounded"
            type="button"
            disabled={connection.status === "connecting" || !record}
            onClick={() => {
              connectAccount();
            }}
          >
            Connect Wallet
          </button>
        ) : (
          <p className="text-red-500 text-sm italic mt-2 text-center w-full">
            An injected Ethereum provider such as{" "}
            <a href="https://metamask.io/">MetaMask</a> is needed to
            authenticate.
          </p>
        )}
      </div>
    </>
  )
}

In the code snippet above,

• The useViewerConnection hook is used to set up a state variable for the user's connection status, connect and disconnect.
• isWindow to set the initial state of the the window to avoid React hydration error
• The useViewerRecord hook is used to retrieve the user's basic profile data.
• The createAuthProvider function creates an EthereumAuthProvider object using the window.ethereum provider.
• The connectAccount function calls createAuthProvider and connects to the user's account using connect(authProvider).
• The JSX code conditionally renders a button based on the user's connection status and the availability of an ethereum provider in the window object.
• If the user is already connected, the button will enable them to disconnect. If the user is not yet connected and an ethereum provider is available, the button will enable them to connect. But if the user is not connected and no ethereum provider is available, a message will be displayed to inform the user that an injected Ethereum provider like MetaMask is required to authenticate.

Testing out the authentication functionality, you should have something similar to what is shown below:

How to Create or Update a User Profile

In the previous section, you learned how to successfully authenticate users. Next, you will implement functionality to create and update an authenticated user with the following code snippet:

pages/index.js

//...


export default function Home() {
// Use the useState hook to create state variables and functions to update them
  const [name, setName] = useState("");
  const [bio, setBio] = useState("");
  const [username, setUsername] = useState("");

  //...

// Define an asynchronous function called updateProfile to update the profile information
  async function updateProfile() {
    // If any of the required fields are empty, return early and do not update
     if (!name || !bio || !username) {
       return;
     }

     // Use the merge method to update the record with the new information
     await record.merge({
       name,
       bio,
       username,
     });
   }

  // Render the component's UI
  return (
    <>

    {/* ... */}

    <div className="flex items-center justify-center pt-20 font-sans overflow-hidden">
          <div className="max-w-md w-full mx-auto">
            <div className="bg-white p-10 rounded-lg shadow-lg">
              <form>
               {/* ... */}
              </form>
            </div>
            {connection.status === "connected" && record && record.content ? (
              <div className="flex flex-col items-center mt-8">
                <h2 className="text-3xl font-bold mb-6 text-gray-900">
                  Profile Information
                </h2>
                <div className="w-full max-w-md bg-white p-8 rounded-lg shadow-lg">
                  <p className="mb-4">
                    <span className="font-bold text-gray-700 mr-2 text-lg">
                      Name:
                    </span>{" "}
                    <span id="nameOutput" className="text-lg">
                      {record.content.name || "No name set"}
                    </span>
                  </p>

                  <p className="mb-4">
                    <span className="font-bold text-gray-700 mr-2 text-lg">
                      Bio:
                    </span>{" "}
                    <span id="bioOutput" className="text-lg">
                      {record.content.bio || "No bio set"}
                    </span>
                  </p>
                  <p>
                    <span className="font-bold text-gray-700 mr-2 text-lg">
                      Username:
                    </span>{" "}
                    <span id="usernameOutput" className="text-lg">
                      {record.content.username || "No username set"}
                    </span>
                  </p>
                </div>
              </div>
            ) : (
              <div className="mt-8">
                <div className="bg-white p-8 rounded-lg shadow-lg">
                  <p>No profile found.</p>
                </div>
              </div>
            )}

          </div>
        </div>
    </>
  ) 
}

In the code above,

• The component uses the useState hook to manage the state of three variables: name, bio, and username.
• There's an async function called updateProfile that is responsible for merging the current state of the variables into a record.
• If any of the variables is empty, the updateProfile function returns without updating the record.
• There are three conditional statements that render a different UI based on whether a record is found or not.
• The first conditional statement checks whether the record is still loading, and if it is, it displays a Loading... message.
• The second conditional statement checks whether there's no record content and the connection status is connected. If this is true, it displays a No profile found. message.

The third conditional statement checks whether the record content exists. If it does, it displays the profile information, which includes the user's name, bio, and username.

You are almost there. In the form tag, update the name, bio and username input field with the following code:

<div className="mb-6">
  <label
    className="block text-gray-700 font-bold mb-2"
    htmlFor="name"
  >
    Name
  </label>
  <input
    //...
    onChange={(e) => {
      setName(e.target.value);
    }}
  />
</div>
<div className="mb-6">
  <label
    className="block text-gray-700 font-bold mb-2"
    htmlFor="bio"
  >
    Bio
  </label>
  <textarea
    //...
    onChange={(e) => {
      setBio(e.target.value);
    }}
  ></textarea>
</div>
<div className="mb-6">
  <label
    className="block text-gray-700 font-bold mb-2"
    htmlFor="username"
  >
    Username
  </label>
  <input
    //...
    onChange={(e) => {
      setUsername(e.target.value);
    }}
  />
</div>

In the code snippet above, setName, setBio, and setUsername are functions provided by the useState hook that update the state of name, bio, or username.

Next, the Update Profile button.

//...

 <button
     className="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded"
     type="submit"
     disabled={!record.isMutable || record.isMutating}
     onClick={() => updateProfile()}
 >
    {record.isMutating ? "Updating..." : "Update Profile"}
</button>

//..

In the code snippet above, the button is disabled when the record is not mutable or is currently mutating.

When the button is clicked, it calls the updateProfile function, which is responsible for updating the user's profile information. If the record mutates, the button will display Updating.... Otherwise, it will display Update Profile.

You can test out the application similar to what is shown below.

Kindly find the complete code on GitHub repository here.

Conclusion

In this post, you learn about Decentralized Identity, Decentralized Identifiers, Ceramic networks, why Ceramic network is useful, and how to build a decentralized identity profile with Ethereum on Ceramic Networks.

References

• Ceramic Network
• Ceramic Documentation
• Decentralized Identity - Ethereum

I'd love to connect with you at Twitter | LinkedIn | GitHub | Portfolio

See you in my next article. Take care!

The first time I tried to learn blockchain development, I felt overwhelmed.

This tutorial you're reading is what I wish I could send back in time to myself.

This will give you a strong foundation in blockchain development, and set you up for success in coding your own smart contracts.

In in addition to my explanation and code examples, I've included lots of videos you can use to supplement your learning.

Prerequisites

This tutorial assumes that you understand some foundational coding concepts. One of these that will be particularly helpful is the concept of object-oriented programming (OOP).

What is Blockchain?

The Blockchain is a network of transactions or assets called blocks where every block is connected to the others. Everyone here has equal access to the data circulating within the network.

You can see blockchain as a document that holds the details of transactions made by a group of people where everyone has a copy. Everyone must agree upon any updates before they are accepted.

Anyone who tries to mutilate their document without the others' consent is seen as fraudulent and will suffer predefined consequences.

For example, imagine that a group of friends (Njoku, Samson, and Ebere) decides to start a peer-to-peer savings account that must run for a certain period before a withdrawal is possible. The three agree that no one will be the boss, and each person will have equal access to the account to ensure trust. So they open an account.

Each time one of them deposits money, everyone gets a new account history document emailed to them. Whenever they decide to add a new member, the person becomes part of the signatories and gets a copy of the account history.

Everyone must consent before a withdrawal happens outside the proposed date. Not following these terms will incur consequences such as losing all of a person’s savings or leaving the association after paying a fine.

Blockchain is known as a decentralized technology since data and authority are shared equally among everybody in the network. It differs from centralized applications where the company owns the data, and the consumers just hope their data isn’t misused.

Examples of decentralized applications include Bitcoin and Ethereum, while centralized applications include Facebook and Google.

Blockchain technology falls under the category of Web 3 simply because it is the third phase of the internet in which users can read, write, and own data. Web 1 was the stage where users could only read data. Web 2 emerged sometime around the early 2000s and is the phase in which users can read and write data.

How Blockchain Works

In this section, I will explain what happens in a blockchain application behind the scenes.

We will begin by looking at how it works in theory and then how we can replicate it using a programming language that many devs already know – JavaScript.

Theory Behind the Blockchain

A blockchain is a connection of many blocks. So it begins with one block called the genesis block. Among other things, a block contains a hash, the previous block hash, and at least one transaction.

Every block in the blockchain keeps a record of its hash and the previous block’s hash to keep the network safe from hackers.

This implies that for a hacker to gain access and break the network, they need to generate the hashes and match them to the right block without breaking other blocks. Now that sounds really stressful and almost impossible. That is how secure blockchains are.

Next, any user on the network can perform at least one transaction. If the user has completed a set of transactions they need at a time, they can use those transactions to create a block. The block may now be added to the others.

The whole process of adding a new block is known as mining. The process secures and verifies the transactions contained in a block.

The hash of a block gets generated when mining. The process of calculating the hash is known as proof of work.

Blockchain in Practice

Let's use some JavaScript object-oriented programming to demonstrate how blockchain works. We are using the OOP method because blockchain programming uses the same pattern.

But before we start building, let's learn how to generate the hash for every block in a blockchain.

How to generate a block's hash

There are a lot of libraries for generating a block's hash. But we will use the SHA256 library for this tutorial. SHA256 is the most popular and is used by many renowned companies.

The SHA256 library takes any data given to it and returns a 64-character long string. Every string passed to the SHA256 library will always return the same 64-character long string every time.

You can check out https://emn178.github.io/online-tools/sha256.html and play around with the UI to see how it works.

Blockchains do not use just any hash generated because of security reasons. It specifies what the first few characters must look like for the hash to be accepted. This means that the hash will have to be generated several times, and a record of what changes on each iteration will be kept for reference purposes.

For example, a blockchain may specify that the only acceptable hash must contain three zeros at the beginning.

To calculate the hash, we need to add a number known as a nonce to the string being hashed. The nonce usually starts from zero and is incremented every time the hash is generated until a hash beginning with three zeros is found. Then the hash and the nonce will be stored for reference purposes.

The code below will calculate the hash for "man":

SHA256("man").toString()

However, we may run the function several times to get a string with three zeros at the beginning. Since the function will always return the same result, we need to add a number to the string and increment it until we get the hash we want.

The code we'd use for that will look like this:

let hash = "";
let nonce = 0;

while (hash.substring(0, 3) !== "000") {
  nonce++;
  hash = SHA256("man" + nonce).toString();
}

console.log(nonce);
console.log(hash);

This code will produce 000d6575d4670dae39df9944e54c27dc4837beab1db23e2de264a7c1a3f38b1a after 5707 times instead of 48b676e2b107da679512b793d5fd4cc4329f0c7c17a97cf6e0e3d1005b600b03.

This level of security measures taken to build blockchain applications makes them very reliable and acceptable.

Now that we understand how a hash is generated in blockchain, let's get back to demonstrating how blockchain works.

How Blockchain Works Using JavaScript

First, create a directory called intro_to_blockchain. Then open the directory in a terminal.

Run the following command and hit enter for all the prompts to initialize the project:

npm init

Create 2 files: blockchain.js and test.js:

touch blockchain.js test.js

We will use the blockchain.js file to write the code that emulates how blockchain works and use test.js to test the code and see the result.

In the blockchain.js, enter the following code:

class Blockchain {
    constructor () {
        this.chain = [this.createGenesisBlock()];
        this.pendingTransactions = [];    
    }
}

The code above declares a class named Blockchain. The constructor function is used to initialize the chain and pendingTransactions array.

The chain array will contain every block or group of transactions added to the network. The pendingTransactions array will hold all transactions that have not been added to a block.

Remember that a blockchain starts with a genesis block. That is why the chain array is initialized with an array containing a function that creates the genesis block. You may hardcode the genesis block into the chain array, too.

We now need to build the createGenesisBlock function. Use the code below:

  createGenesisBlock() {
    return {
      index: 1,
      timestamp: Date.now(),
      transactions: [],
      nonce: 0,
      hash: "hash",
      previousBlockHash: "previousBlockHash",
    };
  }

The function will only execute once because the constructor function runs only once – at the beginning of the program.

It is also the only time a random uncalculated hash or previousBlockHash is used because it is the first block in the chain and does not carry any transactions.

The next thing to do is to make a function to get the last block. Use the code below:

  getLastBlock() {
    return this.chain[this.chain.length - 1];
  };

This code will enable us to access the details of the most recent block added. Remember that we need to keep track of the previous block's hash.

Let's now add the code to calculate the hash of a block.

generateHash(previousBlockHash, timestamp, pendingTransactions) {
    let hash = "";
    let nonce = 0;

    while (hash.substring(0, 3) !== "000") {
      nonce++;
      hash = SHA256(
        previousBlockHash +
          timestamp +
          JSON.stringify(pendingTransactions) +
          nonce
      ).toString();
    }

    return { hash, nonce };
  }

To ensure that this works, install the SHA256 library using the following command:

npm i sha256

Import it at the top of your blockchain.js file like this:

const SHA256 = require("sha256");

We will now add a function that creates our transactions and adds them to the list of pending transactions. Enter the following code:

  createNewTransaction(amount, sender, recipient) {
    const newTransaction = {
      amount,
      sender,
      recipient,
    };

    this.pendingTransactions.push(newTransaction);
  }

The time has now arrived for us to build the last function – createNewBlock. It will enable us to add the pending transactions to a block, calculate the hash, and add the block to the chain. Type the code below:

  createNewBlock() {
    const timestamp = Date.now();
    const transactions = this.pendingTransactions;
    const previousBlockHash = this.getLastBlock().hash;
    const generateHash = this.generateHash(
      previousBlockHash,
      timestamp,
      transactions
    );

    const newBlock = {
      index: this.chain.length + 1,
      timestamp,
      transactions,
      nonce: generateHash.nonce,
      hash: generateHash.hash,
      previousBlockHash,
    };

    this.pendingTransactions = [];
    this.chain.push(newBlock);

    return newBlock;
  }

The code above uses the getLastBlock function to access the previous block's hash. It calculates the hash of the current block, adds all the detail of the new block in an object, clears the pendingTransactions array, and pushes the new block into the chain.

Let's export the Blockchain class to be able to access it outside the file:

module.exports = Blockchain;

How to Test the Code

We want to test the code we have written so far and see if it works as expected. We will navigate to the test.js file and begin by importing the Blockchain class that we exported a moment ago like this:

const Blockchain = require("./blockchain");

Now that we have the class here, we can make an instance of it and name it bitcoin:

let bitcoin = new Blockchain();

You may call it whatever you see fit, but I will use bitcoin because it is popular.

Let's now see what we have in bitcoin by default. To do that, we will log it to the console like this:

console.log(bitcoin);

We will now open the project in a terminal and run the following command:

node test

It should output the following:

Default Output

In the output above, we have the chain array containing the genesis block and the pendingTransactions array containing nothing.

You will recall that the constructor function contains all those data and it runs once at the beginning of the program.

To add a new transaction, use the code below:

bitcoin.createNewTransaction(
  "100",
  "0xBcd4042DE499D14e55001CcbB24a551F3b954096",
  "0xa0Ee7A142d267C1f36714E4a8F75612F20a79720"
);

The first parameter is the amount, the second is the sender, and the third is the recipient just as we specified while creating the function.

If you run node test again, you should have one item in the pendingTransactions array like this:

One pending transaction added

To create or mine a block, enter the following code:

bitcoin.createNewBlock();

You should get the output below this time:

You will notice that there are now two (2) blocks in the chain and no more transactions in the pendingTransactions array.

Some things to note in the second block are the nonce and the hash. The nonce is 1404. That means it took 1404 iterations to get the correct hash for this block.

To see the transactions in the second block, we use the following code:

console.log("\n");
console.log("Second Block Transactions", bitcoin.chain[1].transactions);

Now we have the result below:

That looks good! It shows that all our functions work as intended. And that is what goes on behind the scenes of many blockchain applications.

You've just learned how blockchain works. But you shouldn’t build a blockchain application solely on this program idea. There is much more to learn to enable you to build real-world DApp. Still, what we have done so far will help you dive more into learning web3.

One of the things you need to learn is a blockchain programming language such as Solidity and other blockchain frontend libraries such as Web3js and Etherjs.

I'll now introduce you to smart contracts using Solidity.

How to Write a Smart Contract

In this section, we will cover all you need to know about smart contracts and the Solidity programming language.

What is a Smart Contract?

A smart contract is a program stored on the blockchain. It holds certain conditions that must be met before it executes.

Smart contracts take after traditional contracts. But they're different because they are run by a computer automatically when the predefined terms are met.

What is Solidity?

Solidity is the main programming language used to build most smart contracts because it is specifically designed for that purpose. It follows the OOP pattern that we demonstrated using JavaScript and borrows the typed nature of TypeScript. So while some syntax might differ from what you already know, it is not too far-fetched to grasp.

We will be learning the basics of Solidity by using it to build a smart contract that enables users to send funds to each other.

Don't worry, you will not have to set up another project. We will use the remix playground to do everything – write the code, compile, debug, and test.

Let's now head over to https://remix.ethereum.org/. You should have the following screen stare at you for a while:

Remix welcome page

Remix is getting everything ready for you. Just be patient 😊

When it's done, you should have the following screen:

This playground provides us with all we need to write our first smart contract.

Let's start by deleting the file created for us by default. To do that, click on the first icon below the remix logo.

Right-click on the file name in the explorer section and select delete:

Click OK in the pop-up menu.

We will now create a new file named Blockchain.sol by clicking the document icon marked red in the image below and type the name of the file in the space provided:

.sol is the extension used for solidity files. The blank space is where we will type our code.

Solidity code always begins with the line below:

// SPDX-License-Identifier: UNLICENSED

Without this code, you will get an error. It is just like saying that you accept the terms and conditions of writing Solidity.

The next thing to do is to state the Solidity version you want to use. I will use the following code:

pragma solidity ^0.8.7;

The caret (^) sign indicates that the program will be compatible with higher versions of solidity. We can now start the program.

The first thing to do is to define a Class named Blockchain. However, the keyword for Class in solidity is contract. So we have:

contract Blockchain {

}

Inside the contract above, we will create a data-type called BlockStruck with the code below:

struct BlockStruck {
    uint256 index;
    uint256 timestamp;
    uint256 amount;
    address sender;
    address recipient;
}

Solidity allows us to create any data-type that we see fit using the struct keyword, which is short for structure.

We define all the keys we expect a value for in the struct. Since solidity is a strongly typed language, we specified a data-type before each key. The struct is similar to Object in JavaScript.

uint indicates that a variable is an integer. Adding a number after it (such as uint256 or uint18) specifies the maximum size it should take, but uint assumes uint256 by default.

address, on the other hand, indicates that a variable is a wallet address. There is also the string data-type.

The next thing that we want to define is an event. An event is usually triggered at the end of a function's execution to send data to the frontend. You can see it like console.log. Some people also use it as a cheap way of storage.

We want to define a BlockEvent that we will trigger after adding a block to the chain. Enter the following code below the BlockStruct:

event BlockEvent(uint256 amount, address sender, address recipient);

Unlike struct, circular braces are used for an event, and their keys are separated by commas (,). Also, notice that struct does not end with a semicolon, but event does.

Now that we have defined the structure of blocks, let's use it to setup an array of blocks called chain like this:

BlockStruck[] chain;

The code above defines the chain to be an array of BlockStruct. As always, we specify the data-type before the variable name.

Next, define a variable to keep track of how many blocks are in the chain:

uint256 chainCount;

You may choose to assign it a value on the same line (uint256 chainCount = 0;) or do it in the constructor function like this:

constructor() {
    chainCount = 0;
}

We will now define three (3) functions: addBlockToChain (to add blocks to the chain), getChain (to return all the blocks added to the chain), and getChainCount (to get the number of blocks added to the chain).

addBlockToChain function

The code below begins the function:

function addBlockToChain(uint256 amount, address payable recipient) public {

}

Like the functions you already know, it begins with the function keyword followed by the name of the function, and the argument it expects in braces.

One of the arguments (recipient) has a flag called payable, indicating that the wallet address is eligible to receive funds. Next to it is the function's visibility flag (public).

Visibility defines who can call a function or variable. It can be public, private, internal, or external.

1. A public function can be called by any contract.
2. private functions can only be called inside the contract where they are defined.
3. Only contracts that inherit internal functions can call them.
4. external functions are only accessible by other contracts.

In the addBlockToChain, we start by incrementing the chainCount by one like this:

chainCount += 1;

Next, add the block of a transaction to the chain like this:

        chain.push(
            BlockStruck(
                chainCount,
                block.timestamp,
                amount,
                msg.sender,
                recipient
            )
        );

The BlockStruct takes values corresponding to the keys set when defining the struct. It is then added to the chain array using the .push method. Now we have a new block in the chain.

Finally, we trigger the BlockEvent we created a while ago:

emit BlockEvent(amount, msg.sender, recipient);

emit is the keyword used to call an event. As with the BlockStruct, the BlockEvent takes the values as they correspond to the keys set when defining the it.

The addBlockToChain function now looks like this:

    function addBlockToChain(uint256 amount, address payable recipient) public {
        chainCount += 1;

        chain.push(
            BlockStruck(
                chainCount,
                block.timestamp,
                amount,
                msg.sender,
                recipient
            )
        );

        emit BlockEvent(amount, msg.sender, recipient);
    }

getChain function

This function takes no argument but returns a BlockStruct. We will use the following code:

    function getChain() public view returns (BlockStruck[] memory) {
        return chain;
    }

The program returns the chain, an array of all blocks.

Something to note in the function above is that we used view to show that this function returns a value. We also indicated the kind of data type we expect to be returned (returns (BlockStruck[] memory)) and the storage type to be used (memory).

There are two main storage types in solidity: Storage and Memory. Storage is the default type of storage used to hold data permanently for a program while Memory is temporary and is less expensive in terms of gas.

Gas is a fee paid to execute smart contracts. Don't worry about that. We have some dummy gas that will enable us to test our program.

getChainCount function

Like the getChain, this function also takes no argument. It returns the number of blocks added to the chain so far. See the code below:

    function getChainCount() public view returns (uint256) {
        return chainCount;
    }

That completes the smart contract that we intended to create. Now the code looks like this:

// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.7;

contract Blockchain {
    struct BlockStruck {
        uint256 index;
        uint256 timestamp;
        uint256 amount;
        address sender;
        address recipient;
    }

    event BlockEvent(uint256 amount, address sender, address recipient);

    BlockStruck[] chain;
    uint256 chainCount;

    constructor() {
        chainCount = 0;
    }

    function addBlockToChain(uint256 amount, address payable recipient) public {
        chainCount += 1;

        chain.push(
            BlockStruck(
                chainCount,
                block.timestamp,
                amount,
                msg.sender,
                recipient
            )
        );

        emit BlockEvent(amount, msg.sender, recipient);
    }

    function getChain() public view returns (BlockStruck[] memory) {
        return chain;
    }

    function getChainCount() public view returns (uint256) {
        return chainCount;
    }
}

How to Compile the Smart Contract

We need to compile the code to check if there are errors that we need to fix. The steps below will help us do just that.

Click on the third icon on the left side menu of the remix IDE:

Ensure that the solidity version selected matches the one you specified at the beginning of the smart contract. Then click the Compile button:

The compilation was successful since we have no errors. Beautiful 🥰.

How to Deploy the Smart Contract

Now that compilation is successful, let's deploy the contract.

Click on the fourth icon in the side menu:

Select Remix VM (London) for the ENVIRONMENT. It has ten (10) accounts with 100 dummy ethers each that you may use for test purposes. Then click the Deploy button:

Now when you scroll to the bottom, you will find the Blockchain contract under Deployed Contracts. Click the arrow by the deployed contract name to see the functions of the contract that you can interact with.

There are three (3) functions in the image above that match the three (3) functions we defined in our smart contract. Remix automatically creates a UI for you to test your contracts as soon as you deploy them

How to Test the Smart Contract

We will now test the functions we created to see how they respond.

How to test the addBlockToChain function

To test the addBlockToChain function, click the caret (^) icon by the side of the function button and input box. That drops down a form. Fill in 10 for the amount, and fill in one of the ten 10 account addresses for the recipient:

Click the transact button.

Note that you cannot send funds to the same address you used to deploy the contract. You must choose a different account.

How to test the getChain function

Click the getChain button to reveal the blocks in the chain so far:

It returns a tuple, which is a kind of array. Recall that chain is supposed to be an array containing a list of blocks.

How to test the getChainCount function

To get the number of blocks added, click the getChainCount button:

And just as we defined it, it returns a uint. There is just one item in the chain for now, but as you keep adding more blocks, the number will increase.

Walah! Did we come this far? 😳 How Awesome 😍.

Congratulations on sticking to the end of this tutorial!

You are now ready to explore all that you can do with blockchain.

Conclusion

Blockchain is redefining the internet and has come to stay. The difficulty I encountered trying to learn the ropes of this new technology moved me to document this beginner-friendly guide. I hope that it helps everyone still struggling out there.

In this tutorial, you learned what blockchain is, how it works and what goes on behind the scenes. We demonstrated how it works using the OOP pattern of JavaScript and then concluded with a brief introduction to how to build smart contracts using the solidity programming language and remix IDE.

I recommend that you keep learning and getting better at building blockchain applications by creating the following projects in the order they are listed (by increasing difficulty):

Hello World
Simple Storage
Voting Smart Contract
Ether Wallets
Multi Send
Time Lock Smart Contract
ERC20 Token
Token Wallet
Air Drop
ICO

These projects will challenge you to do research and sharpen your blockchain skill.

Happy Chaining!

Over the past 9 months, several of our instructors have been hard at work on a comprehensive NEAR curriculum. This will focus on NEAR's blockchain protocol and the NEAR tool ecosystem.

This curriculum is made possible by NEAR Foundation, who gave our charity a grant to 100% fund development of this curriculum.

What will it contain?

The curriculum will contain at least ten interactive practice projects that will guide you through learning the NEAR protocol and their tools.

You'll learn how to build and deploy your own smart contracts, dApps, work with NEAR command line tools, and much more. There will also be five challenging integrated projects to test your knowledge.

How will it work?

These courses will run in a docker container using VS Code and the freeCodeCamp Courses extension.

Here's a Sample of the first Project

When Will it be Available?

The courses will be released in batches. As we finish creating a group of projects, typically consisting of two interactive practice projects and one integrated project, they will be released for you to complete. The first group is available now! and consists of these projects:

• Learn How to Set Up NEAR by Building a Hello World Smart Contract
• Learn NEAR Smart Contracts by Building a Word Guessing Game
• Build a Sentence Making Smart Contract

How to Run the Courses

Follow the steps below to run the courses

Developer Environment Prerequisites

Before you get started, make sure you have these installed on your computer:

1. Docker Engine
2. VS Code and the Dev Containers extension
3. Git

How to Run the Curriculum in Docker

Follow these instructions to clone the repo and run the courses:

1. Open a terminal and clone the near-curriculum repo with:

   git clone https://github.com/freeCodeCamp/near-curriculum.git
   

2. Navigate to the near-curriculum directory, and open it in a VSCode workspace with:

   code .
   

3. Press Ctrl / Cmd + Shift + P to open the command palette, and run Dev Containers: Rebuild Container and Reopen in Container. VS Code will build the container to run the projects in, it will take a few minutes the first time.

4. Once it's finished, press Ctrl / Cmd + Shift + P again and run freeCodeCamp: Run Course to start the courses. This will also take a moment.
5. The simple browser will open when it's done. If it's a blank white page, use the refresh button to update it and see the courses home page.
6. Click on one of the available projects to start a project.
7. Follow the instructions to complete the project.
8. Have fun!

If you want to switch projects, click the freeCodeCamp logo at the top to get back to the home page.

Sign up for updates

Fill out this google form to sign up to receive updates when new courses are released.

While You're Waiting

While you are waiting for these courses, you can try the Web3 curriculum (also under development). It will teach you many Web3 and blockchain concepts you will want to know for the NEAR curriculum.

Learn more about NEAR Foundation

You can learn more about NEAR Foundation by visiting their website.

Over the past 11 months, we've made considerable progress on our Web3 curriculum. Today I'm thrilled to say that parts of this curriculum are now in open beta. You can try them today.

Before we get into the details, I want to thank the KaijuKingz community, who made a donation to freeCodeCamp that made development of these courses possible. You can read more about their gift to the freeCodeCamp community here.

How to Approach These Web3 Courses

As a prerequisite for this course, we recommend first learning full stack web development. You can do this by working through the first 7 freeCodeCamp certifications and building their projects:

1. Responsive Web Design
2. JavaScript Algorithms and Data Structures
3. Front End Development Libraries
4. Data Visualization
5. Relational Database
6. Back End Development and APIs
7. Quality Assurance

We also recommend you know some knowledge of basic blockchain development concepts. freeCodeCamp has an in-depth 32-hour course that covers this, taught by developer and instructor Patrick Collins.

We also recommend learning some Rust, which you can learn interactively using freeCodeCamp's Rust course.

Again, these prerequisites are just our recommendations. Feel free to just dive in and return to those resources as you see fit.

Right now, we have designed five integrated Web3 projects for you to complete:

1. Build a Video Game Marketplace Blockchain
2. Build a Fundraising Smart Contract
3. Build a Peer-to-Peer Network
4. Build a Web3 Client-Side Package for your dApp
5. Build a Smart Contract in Rust

Each of these projects has its own set of instructions with tasks for you to fulfill, and tests to ensure you've implemented your project correctly. Complete all the tasks and get all the tests to pass to finish each project.

These 5 projects are just the beginning

We are also developing 10 interactive Web3 practice projects.

These will walk you through all the Web3 concepts you need to know to build these 5 integrated projects we're releasing today.

Why are we releasing the hard part (the 5 integrated projects) first? For the die-hard Web3 enthusiasts who don't mind using watching Patrick's course, reading official documentation, and referencing the many other free Web3 tutorials out there.

Soon it will be a smoother ride for anyone to learn these tools and concepts. But we wanted to first get something out there for the hardcore crowd.

Available interactive projects

As of January 2023, the first group of interactive practice projects is now fully available. They will teach you the concepts you need to know to complete the first integrated project. The new courses are:

1. Learn Digital Ledgers by Building a Blockchain
2. Learn Proof of Work Consensus by Building a Block Mining Algorithm
3. Learn Digital Signatures by Building a Wallet

The Web3 Curriculum is in open beta. We welcome your feedback and bug reports.

Note that these are in open beta – meaning that we will continue to refine them with your feedback.

You can help by joining our new Web3 Curriculum Discord server, introducing yourself, and helping other people who get stuck trying to build these 5 integrated projects.

You can also sign up for updates These will make it a lot easier to build these 5 integrated projects So in a way, you actually doing the hardest, most ambiguos part Sign up for updates below for when new courses are released.

How will it work?

The courses will run in a docker container using VS Code and the freeCodeCamp Courses extension.

Here's a sample

How to Run the Courses

Follow the steps below to run the courses

Developer Environment Prerequisites

Before you get started, make sure you have these installed on your computer:

1. Docker Engine
2. VS Code and the Dev Containers extension
3. Git

How to Run the Curriculum in Docker

Follow these instructions to clone the repo and run the courses:

1. Open a terminal and clone the web3-curriculum repo with:

   git clone https://github.com/freeCodeCamp/web3-curriculum.git
   

2. Navigate to the web3-curriculum directory, and open it in a VSCode workspace with:

   code .
   

3. Press Ctrl / Cmd + Shift + P to open the command palette, and run Dev Containers: Rebuild Container and Reopen in Container. VS Code will build the container to run the projects in, it will take a few minutes the first time.

4. Once it's finished, press Ctrl / Cmd + Shift + P again and run freeCodeCamp: Run Course to start the courses. This will also take a moment.
5. The simple browser will open when it's done. If it's a blank white page, use the refresh button to update it and see the courses home page.
6. Click on one of the available projects to start a project.
7. Follow the instructions to complete the project.
8. Have fun!

If you want to switch projects, click the freeCodeCamp logo at the top to get back to the home page.

Sign up for updates

Fill out this google form to receive updates when new courses are released.

Other Courses

We are also creating courses around the Solana and NEAR protocols.

View the Solana announcement article. View the NEAR announcement article.

Or, check out the web3.freecodecamp.org domain where we showcase all the courses.

Logging into a website via third parties is ubiquitous online. Almost every other member-based website allows you to log in with accounts like Facebook, Twitter, and Google.

If you’ve ever visited NFT marketplaces like OpenSea or Rarible, you would have noticed they allow you to sign in with a crypto wallet like MetaMask.

This login process affirms you’re the owner of the Ethereum address in question and allows the system to authenticate your access. Very similar to how a username and password would allow you access to a gated part of a website.

Prerequisites

Before starting this tutorial, I’ll assume you have a basic understanding of Laravel, and that you can initialise a new project in your environment. Even though this tutorial is Laravel-focused, with some tweaking you can apply this to any other PHP project. The concepts remain the same.

I’ve tried to keep this as generic as possible. I only focus on the MetaMask signing and validation, without restricting you to using it with specific front-end technologies (like React or Vue) or authentication scaffolding (like Breeze or Jetstream). This gives you the freedom to implement it with minimal effort into an existing project.

We’ll need the following before we start:

• A new or existing Laravel project.
• MetaMask installed in your browser.

Boilerplate

We’ll start out with some boilerplate code by importing Bootstrap 5 and creating a simple “Log in with MetaMask” button.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>MetaMask Login</title>
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-1BmE4kWBq78iYhFldvKuhfTAU6auU8tT94WrHftjDbrCEXSU1oBoqyl2QvZ6jIW3" crossorigin="anonymous">
    <script src="https://cdn.ethers.io/lib/ethers-5.2.umd.min.js"></script>
</head>
<body>
<div class="container">
    <div class="row">
        <div class="col-12 text-center">
            <button class="btn btn-primary mt-5">Log in with MetaMask</button>
        </div>
    </div>
</div>
</body>
</html>

Easy enough. 😀

We’re also importing the ethers.js library that will allow us to interact with the Ethereum blockchain via MetaMask, which in this case acts as the interface to the provider (Infura by default).

Quick tip:

Providers allow us to interact with the Ethereum blockchain. To connect to the network, you need access to a node. Depending on the type of node, it could require a large amount of disk space and bandwidth. Running a node can also be a complex process, especially if you want to focus on development rather than maintaining and operating a node.

Enter, the provider! Companies like Infura provide these nodes as a service, so you don’t need to worry about running your own. Instead, you can access this functionality via their APIs.

You may run into older tutorials that state MetaMask injects web3.js (a library providing similar functionality to ethers.js) into the page by default. This is no longer the case.

Detect the Provider

We’ll start off our new web3Login() function by checking that the browser has a provider available. This would be the case if you have MetaMask installed. You can also test this code where MetaMask is not installed (for example, an incognito window) to confirm the detection works.

Add the click event to the button:

<button class="btn btn-primary mt-5" onclick="web3Login();">Log in with MetaMask</button>

And start off the function with our detection snippet in our <head> below the ethers.js import:

<script>
    async function web3Login() {
        if (!window.ethereum) {
            alert('MetaMask not detected. Please install MetaMask first.');
            return;
        }
    }
</script>

Go ahead and test this in a browser with no MetaMask installed.

Install Laravel Dependencies

Before we continue with the front-end login process, we need to put some endpoints in place. Our login script will need these so the user can sign a message with their wallet, and our system can then verify their signature.

We need to install two dependencies via Composer to help us perform hashing and use elliptic curve cryptography:

composer require kornrunner/keccak
composer require simplito/elliptic-php

Add Laravel Routes

Open your routes/web.php file and add the following routes:

Route::get('/web3-login-message', 'Web3LoginController@message');
Route::post('/web3-login-verify', 'Web3LoginController@verify');

The first route will return the message that needs to be signed, and the second route will verify the signed message.

Create the Login Controller

Now it’s time to create the controller that will generate the message and perform the verification.

Create a new file called Web3LoginController.php in app/Http/Controllers and add the following code to it:

<?php

namespace App\Http\Controllers;

use Elliptic\EC;
use Illuminate\Http\Request;
use Illuminate\Support\Str;
use kornrunner\Keccak;

class Web3LoginController
{
    public function message(): string
    {
        $nonce = Str::random();
        $message = "Sign this message to confirm you own this wallet address. This action will not cost any gas fees.\n\nNonce: " . $nonce;

        session()->put('sign_message', $message);

        return $message;
    }

    public function verify(Request $request): string
    {
        $result = $this->verifySignature(session()->pull('sign_message'), $request->input('signature'), $request->input('address'));
        // If $result is true, perform additional logic like logging the user in, or by creating an account if one doesn't exist based on the Ethereum address
        return ($result ? 'OK' : 'ERROR');
    }

    protected function verifySignature(string $message, string $signature, string $address): bool
    {
        $hash = Keccak::hash(sprintf("\x19Ethereum Signed Message:\n%s%s", strlen($message), $message), 256);
        $sign = [
            'r' => substr($signature, 2, 64),
            's' => substr($signature, 66, 64),
        ];
        $recid = ord(hex2bin(substr($signature, 130, 2))) - 27;

        if ($recid != ($recid & 1)) {
            return false;
        }

        $pubkey = (new EC('secp256k1'))->recoverPubKey($hash, $sign, $recid);
        $derived_address = '0x' . substr(Keccak::hash(substr(hex2bin($pubkey->encode('hex')), 1), 256), 24);

        return (Str::lower($address) === $derived_address);
    }
}

There’s a lot going on in there, so let’s break it down:

Create the message

The message() method creates the message we’ll supply to the front end. It also includes a random token to ensure the message to sign will be different each time.

This token is usually referred to as a nonce, or number used once. In this case, however, it’s a simple random string.

The purpose of this is to prevent replay attacks where, if a malicious user obtained your signature, they could use that to authenticate as you on the website.

The message is then saved to the session and returned to the front end.

Verify the message

Once you have signed the message with your private key via MetaMask, your Ethereum address as well as the signature is sent to the back end for verification.

If it passes the verification, we determine the Ethereum address that signed the message and ensure it matches the Ethereum address sent from the front end during the signing process.

If that passes, we send an OK or ERROR back to the front end.

It’s also at this point where you can add additional logic like logging the member in or creating a new member record if one doesn’t exist for the Ethereum address in question.

Finalise the Front End

Now that the backend is ready, we can complete the rest of the front end. This will involve launching MetaMask, asking the user to sign the message, and then verifying the signature by using our back-end route.

Below is the full web3Login() function:

<script>
    async function web3Login() {
        if (!window.ethereum) {
            alert('MetaMask not detected. Please install MetaMask first.');
            return;
        }

        const provider = new ethers.providers.Web3Provider(window.ethereum);

        let response = await fetch('/web3-login-message');
        const message = await response.text();

        await provider.send("eth_requestAccounts", []);
        const address = await provider.getSigner().getAddress();
        const signature = await provider.getSigner().signMessage(message);

        response = await fetch('/web3-login-verify', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify({
                'address': address,
                'signature': signature,
                '_token': '{{ csrf_token() }}'
            })
        });
        const data = await response.text();

        console.log(data);
    }
</script>

Let’s break it down:

• We first set the provider to the MetaMask provided window.ethereum.
• Next, we grab the message returned from our back end (refresh the page a few times to try this out, you will notice the random token changes every time).
• Once we have the message, we obtain the user’s Ethereum address and ask them to sign the message.

• We then POST the address and signature to the back end (along with our Laravel CRSF token) for verification.
• The result is either an OK or ERROR string which we output in the console.
• At this point you may elect to show an error message (if applicable) or redirect the user if they were registered or logged in during the back-end verification.

Conclusion

In this tutorial we covered the basics of adding a MetaMask login to your website. I hope this has proven useful! Sign up to my newsletter or visit my blog where I’ll share insightful web development articles to supercharge your skills.

Here are some ideas to take your integration one step further:

• Integrate a library like Web3Modal to provide users with various wallet options instead of only MetaMask.
• With the user’s Ethereum address validated, provide them with functions like displaying their ETH balance.

Resources

• Download MetaMask.
• View the ethers.js documentation.
• Latest Laravel documentation.

Nathan's Story

Nathan Flickinger was a college dropout. After a period of homelessness, he vowed to get his life together. It started with using his CompTIA certification he had earned in high school to get a minimum wage job in tech support.

From there, Nathan decided to teach himself to code. After several months of study on freeCodeCamp, he was able to land his first software engineering job.

He became obsessed with Web3 development, and eventually took the plunge and created his own startup. He helped write smart contract code for several Web3 projects. Most notably, KaijuKingz, a monster-inspired collection of cute lizards, each with quirky features. Instead of coffee, they drink radioactive sludge.

People from the KaijuKingz community buy and trade these artistic works through a system called Non-fungible Tokens – essentially, deeds of ownership.

Instead of being stored in a centralized database, these deeds are backed up in computers around the world through a distributed database.

Early on, Nathan decided that if his project was successful, he wanted to donate a large amount of money to freeCodeCamp to help other people to learn how to harness technology to realize their career potential.

And today, he and KaijuKingz have done that. They have donated a million dollars to our nonprofit, for us to use toward our mission of creating free learning resources for people around the world.

I am extremely grateful for Nathan and his colleagues at KaijuKingz, and their willingness to support free, open source education. You can read more about Nathan and his coding journey here.

The Web3 Curriculum

This free curriculum will teach the fundamentals of smart contracts and distributed application development.

It will be a stand-alone curriculum that you can choose to tackle whenever you feel ready. The prerequisites will involve learning full stack web development through the first 7 freeCodeCamp certifications.

We will build this curriculum using the same tools we used to build freeCodeCamp's Relational Database Curriculum. It will teach you Web3 development through building more than a dozen projects.

Frequently Asked Questions

How will this be carbon neutral?

Since all of the development will take place on your own computer and use local blockchains, there will be no carbon emissions. All of freeCodeCamp's cloud servers are already carbon-neutral.

Will all of this be free? Including the blockchain transactions?

Yes. Again, this curriculum will use local blockchains. You will never have to buy any coins or tokens.

Will this curriculum discuss aspects of speculation?

No. This curriculum will be 100% focused on software engineering.

When will this curriculum go live?

We hope to have parts of this curriculum live as early as Summer 2022. In the meantime, we recommend learning web development using the existing freeCodeCamp curriculum.

One way to think about Web3 development is that it's mostly traditional web development with a lot of additional tools for using distributed networks. So everything you learn for traditional web development will also be applicable here.

What about the Data Science curriculum?

The Data Science curriculum is coming along great, and we hope to publish parts of it in the next few months. The Web3 curriculum shouldn't affect the development of the Data Science curriculum – they are being built by separate teams of teachers and developers.

I am a freeCodeCamp alumnus. I learned to code on freeCodeCamp. I used these skills to build a profitable company.

Today, this company – KaijuKingz – is donating $1 million to freeCodeCamp to help them create even more free learning resources.

The freeCodeCamp community has helped me and thousands of other people learn to code by building projects. To set the scene for our donation, I would like to give you some context into my own developer journey – from stumbling upon freeCodeCamp to breaking into Web3.

This is my story.

From Tinkerer to Drop-Out

I was interested in programming from an early age. I would make simple IF-ELSE text-based adventure games for my girlfriend in high school. I guess in my mind, I was some sort of leet developer.

Unfortunately, my school didn't offer any paths to explore programming at the time. Despite this, I did my best to build my skills. I got heavily involved in a computer systems course that allowed students to get certifications like CompTIA, A+, and Net+.

When I was able to go to college, I decided to pursue a CS degree, but I quickly fell behind. Textbooks were expensive. I faced an overall lack of resources. I ended up dropping out.

After struggling with motivation and being homeless for a while, I resolved to get my life back in order.

Clawing My Way Back

I was able to leverage my CompTIA certification to land my first job as a minimum wage computer tech at a large retailer. I dove deeper and deeper into the field, and worked my way up with consistent effort.

I worked my way up to a level-two-support role in the IT department of a large health center. This is where I rediscovered my love for programming and began simple automation tasks. I started writing scripts in Visual Basic. PowerShell became my tool of choice for automating tasks. Little by little I grew into the field.

This is when I first considered learning to become a full-stack developer. I would research tools and dream of the day I could attend a coding bootcamp and become some super awesome full stack developer.

This is when I first discovered free resources like freeCodeCamp and the many YouTube channels that were teaching development. (Shout out to Sentdex <3).

In 2019, I completed the freeCodeCamp Responsive Web Design certification course. I would always check back on freeCodeCamp to read new tutorials and watch some of the new video courses the community created each day. It was fun, I was learning a ton, and it didn't cost me a single penny.

From My First Software Engineer Job to Starting My First Company

In 2020, I landed my first software engineering job working on an eCommerce platform. I continued to sharpen my skills.

Fast Forward to six months ago – I decided to dedicate all my time toward learning the Web3 space, with a focus on decentralization and community building. The result: KaijuKingz.

The KaijuKingz logo, inspired by traditional Japanese brush stroke technique

When creating KaijuKingz, my team decided to set aside some funds for other aspiring developers and creators to learn Web3. We planned on raising enough money to maybe send 3-4 people to a coding boot camp, hopefully change someone's life, and call it a day.

After our success, we realized we had the opportunity to impact more people's lives than we had initially planned. So we reached out to Quincy to discuss how we could leverage our funds and build a Web3 program for aspiring developers. We wanted to help people who were passionate about decentralization and community-owned technology.

We decided to go all-in with his team and their track record for developing effective courses and certifications accessible by anyone in the world.

Plans for the Upcoming freeCodeCamp Web3 Curriculum

Our million-dollar donation will go toward building an entire curriculum on Web3 development. It will cover everything from the basics of programming with Rust and Solidity, to using JavaScript libraries like web3.js.

This curriculum will ultimately provide around 300 hours of free learning to help people go from zero to hero with Web3. The only thing learners will need is access to a computer, and the discipline to complete the curriculum. freeCodeCamp's existing Web2 development curriculum will teach you all of the necessary prerequisite tools.

Quincy and I both feel strongly about the environment. And this curriculum will be carbon-neutral.

I have fundamentally changed my life by learning programming through free resources. Giving back to one of the most comprehensive and effective resources for learning programming (while helping upgrade their curriculum for the future) has given me a purpose. Instead of changing one person's life with this, we hope to change thousands of people's lives, and to bring new developers to the Web3 ecosystem.

Thank you to freeCodeCamp, to the KaijuKingz community who have supported us, and to everyone who's helping build the decentralized future.

Cheers,
Nathan

If you’re reading this then you are a participant in the modern web. The web we are experiencing today is much different than what it was just 10 years ago. How has the web evolved, and more importantly – where is it going next? Also, why do any of these things matter?

If history has taught us anything, these changes will matter a lot.

In this article, I will lay out how the web has evolved, where's it going next, and why this matters.

Think about how the internet affects your life on a daily basis. Consider how society has changed as a result of the internet. Social media platforms. Mobile apps. And now the internet is going through another paradigm shift as we speak.

The Evolution of the Web

The web has evolved a lot over the years, and the applications of it today are almost unrecognizable from its most early days. The evolution of the web is often partitioned into three separate stages: Web 1.0, Web 2.0, and Web 3.0.

What is Web 1.0?

Web 1.0 was the first iteration of the web. Most participants were consumers of content, and the creators were typically developers who build websites that contained information served up mainly in text or image format. Web 1.0 lasted approximately from 1991 to 2004.

Web 1.0 consisted of sites serving static content instead of dynamic HTML. Data and content were served from a static file system rather than a database, and sites didn't have much interactivity at all.

You can think of Web 1.0 as the read-only web.

What is Web 2.0?

Most of us have primarily experienced the web in its current form, commonly referred to as web2. You can think of web2 as the interactive and social web.

In the web2 world, you don’t have to be a developer to participate in the creation process. Many apps are built in a way that easily allows anyone to be a creator.

If you want to craft a thought and share it with the world, you can. If you want to upload a video and allow millions of people to see it, interact with it, and comment on it, you can do that too.

Web2 is simple, really, and because of its simplicity more and more people around the world are becoming creators.

The web in its current form is really great in many ways, but there are some areas where we can do a lot better.

Web 2.0 Monetization and Security

In the web2 world, many popular apps are following a common pattern in their life cycles. Think of some of the apps that you use on a daily basis, and how the following examples might apply to them.

Monetization of Apps

Imagine the early days of popular applications like Instagram, Twitter, LinkedIn, or YouTube and how different they are today. The process usually goes something like this:

1. Company launches an app
2. It onboards as many users as possible
3. Then it monetizes its user base

When a developer or company launches a popular app, the user experience is often very slick as the app continues rising in popularity. This is the reason they are able to gain traction quickly in the first place.

At first, many software companies do not worry about monetization. They strictly focus on growth and on locking in new users – but eventually they have to start turning a profit.

They also need to consider the role of outside investors. Often the constraints of taking on things like venture capital negatively affect the life cycle, and eventually the user experience, of many applications that we use today.

If a company building an application takes in venture capital, its investors often expect a return on investment in the order of magnitude of tens or hundreds of what they paid in.

This means that, instead of going for some sustainable model of growth that they can sustain in a somewhat organic manner, the company is often pushed towards two paths: advertisements or selling personal data.

For many web2 companies like Google, Facebook, Twitter, and others, more data leads to more personalized ads. This leads to more clicks and ultimately more ad revenue. The exploitation and centralization of user data is core to how the web as we know and use it today is engineered to function.

Security and privacy

Web2 applications repeatedly experience data breaches. There are even websites dedicated to keeping up with these breaches and telling you when your data has been compromised.

In web2, you don’t have any control over your data or how it is stored. In fact, companies often track and save user data without their users' consent. All of this data is then owned and controlled by the companies in charge of these platforms.

Users who live in countries where they have to worry about the negative consequences of free speech are also at risk.

Governments will often shut down servers or seize bank accounts if they believe a person is voicing an opinion that goes against their propaganda. With centralized servers, it is easy for governments to intervene, control, or shut down applications as they see fit.

Because banks are also digital and under centralized control, governments often intervene there as well. They can shut down access to bank accounts or limit access to funds during times of volatility, extreme inflation, or other political unrest.

Web3 aims to solve many of these shortcomings by fundamentally rethinking how we architect and interact with applications from the ground up.

What is Web 3.0?

There are a few fundamental differences between web2 and web3, but decentralization is at its core.

Web3 enhances the internet as we know it today with a few other added characteristics. web3 is:

• Verifiable
• Trustless
• Self-governing
• Permissionless
• Distributed and robust
• Stateful
• Native built-in payments

In web3, developers don't usually build and deploy applications that run on a single server or that store their data in a single database (usually hosted on and managed by a single cloud provider).

Instead, web3 applications either run on blockchains, decentralized networks of many peer to peer nodes (servers), or a combination of the two that forms a cryptoeconomic protocol. These apps are often referred to as dapps (decentralized apps), and you will see that term used often in the web3 space.

To achieve a stable and secure decentralized network, network participants (developers) are incentivized and compete to provide the highest quality services to anyone using the service.

When you hear about web3, you'll notice that cryptocurrency is often part of the conversation. This is because cryptocurrency plays a big role in many of these protocols. It provides a financial incentive (tokens) for anyone who wants to participate in creating, governing, contributing to, or improving one of the projects themselves.

These protocols may often offer a variety of different services like compute, storage, bandwidth, identity, hosting, and other web services commonly provided by cloud providers in the past.

People can make a living by participating in the protocol in various ways, in both technical and non-technical levels.

Consumers of the service usually pay to use the protocol, similarly to how they would pay a cloud provider like AWS today. Except in web3, the money goes directly to the network participants.

In this, like in many forms of decentralization, you'll see that unnecessary and often inefficient intermediaries are cut out.

Many web infrastructure protocols like Filecoin, Livepeer, Arweave, and The Graph (which is what I work with at Edge & Node) have issued utility tokens that govern how the protocol functions. These tokens also reward participants at many levels of the network. Even native blockchain protocols like Ethereum operate in this manner.

Native payments

Tokens also introduce a native payment layer that is completely borderless and frictionless. Companies like Stripe and Paypal have created billions of dollars of value in enabling electronic payments.

These systems are overly complex and still do not enable true international interoperability between participants. They also require you to hand over your sensitive information and personal data in order to use them.

Crypto wallets like MetaMask and Torus enable you to integrate easy, anonymous, and secure international payments and transactions into web3 applications.

Networks like Solana offer several hundred digit millisecond latency and transaction costs of a small fraction of a penny. Unlike the current financial system, users do not have to go through the traditional numerous, friction-filled steps to interact with and participate in the network. All they need to do is download or install a wallet, and they can start sending and receiving payments without any gatekeeping.

A new way of building companies

Tokens also brings about the idea of tokenization and the realization of a token economy.

Take, for example, the current state of building a software company. Someone comes up with an idea, but in order to start building they need money in order to support themselves.

To get the money, they take on venture capital and give away a percentage of the company. This investment immediately introduces mis-aligned incentives that will, in the long run, not align well with building out the best user experience.

Also, if the company ever does become successful, it will take a very long time for anyone involved to realize any of the value, often leading to years of work without any real return on investment.

Imagine, instead, that a new and exciting project is announced that solves a real problem. Anyone can participate in building it or investing in it from day one. The company announces the release of x number of tokens, and give 10% to the early builders, put 10% for sale to the public, and set the rest aside for future payment of contributors and funding of the project.

Stakeholders can use their tokens to vote on changes to the future of the project, and the people who helped build the project can sell some of their holdings to make money after the tokens have been released.

People who believe in the project can buy and hold ownership, and people who think the project is headed in the wrong direction can signal this by selling their stake.

Because blockchain data is all completely public and open, purchasers have complete transparency over what is happening. This is in contrast to buying equity in private or centralized businesses where many things are often cloaked in secrecy.

This is already happening in the web3 space.

One example is the app Radicle (a decentralized GitHub alternative) which allows stakeholders to participate in the governance of their project. Gitcoin is another that allows developers to get paid in cryptocurrency for jumping in and working on Open Source issues. Yearn allows stakeholders to participate in decision making and voting on proposals. Uniswap, SuperRare, The Graph, Audius, and countless other protocols and projects have issued tokens as a way to enable ownership, participation, and governance.

DAOs (Decentralized Autonomous Organizations), which offer an alternative way to build what we traditionally thought of as a company, are gaining tremendous momentum and investment from both traditional developers and venture capital firms.

These types of organizations are tokenized and turn the idea of organizational structure on its head, offering real, liquid, and equitable ownership to larger portions of stakeholders and aligning incentives in new and interesting ways.

For example, Friends with Benefits is a DAO of web3 builders and artists, is about a year old, has a market cap of around $125 million as of this writing, and recently received a $10 million round of investment from a16z.

DAOs could encompass an entire post in and of themselves, but for now I'll just say that I think that they are the future of building products and (what we in the past thought of as) companies. Here is a good post outlining the current DAO landscape.

How Identity Works in Web3

In web3, Identity also works much differently than what we are used to today. Most of the time in web3 apps, identities will be tied to the wallet address of the user interacting with the application.

Unlike web2 authentication methods like OAuth or email + password (that almost always require users to hand over sensitive and personal information), wallet addresses are completely anonymous unless the user decides to tie their own identity to it publicly.

If the user chooses to use the same wallet across multiple dapps, their identity is also seamlessly transferable across apps, which lets them build up their reputation over time.

Protocols and tools like Ceramic and IDX already allow developers to build self-sovereign identity into their applications to replace traditional authentication and identity layers. The Ethereum foundation also has a working RFP for defining a specification for "Sign in with Ethereum" which would help provide a more streamlined and documented way to do this going forward. This is also a good thread that outlines some of the ways that this would enhance traditional authentication flows.

How to Build on Web3

I'm a developer who recently transitioned into the web3 space from a traditional development background. So I wanted to start building to get a sense of what the development experience felt like. And I wanted to get an understanding of the types of apps that we can build today.

I dove right in and decided to document some of the things I was doing in a couple of blog posts.

How to Get Into Ethereum, Crypto, and Web3 as a Developer – This is an introduction to the space in general, coming from a developer, for developers looking to break into the industry.

The Complete Guide to Full Stack Ethereum Development – This is a tutorial that teaches you how to build out your first dapp.

The Complete Guide to Full Stack Solana Development with React, Anchor, Rust, and Phantom - This guide dives into Solana to show you how to build a full stack dapp.

If you are interested in learning more about web3 in general, you can check out these posts:

The New Creator Economy - DAOs, Community Ownership, and Cryptoeconomics

The Value Chain of the Open Metaverse

The Rise of Micro-Economies

I first had what I can only describe as a spiritual awakening about 10 years ago to the fact that technology would (figuratively) rule the world. And since then, I've been obsessed with wanting to understand how software works and how to build it.

Since that moment, my life has changed significantly for the better. I can only attribute it to the simple fact that I have relied not only on my own instincts, but on those of people much smarter and more experienced than I am.

My hypothesis is this: try to find and follow the lead of those who have exhibited a long track record of success, find interests in their wake, and do my best to excel at them (while continuing to explore my own curiosities).

This approach has led me to try and master JavaScript, and then React, and finally to build a successful consultancy. All this ultimately landed me on a team at AWS in a life changing experience that lasted a little over 3 years. All of this with no high school diploma or college degree.

During this time (like many developers) I've relentlessly dived into books, podcasts, blog posts, YouTube videos, and source code of every kind. But there has always been a topic that has captured my curiosity the most – futurism.

Futurists like Gerd Leonhard and Michio Kaku speak of a future that's sometimes beautiful and sometimes bleak. But it's always with the passion and phrasing that make your thoughts wander and move past the current moment in time and into a mind boggling world that does not yet exist.

I recently had another "aha" moment, similar to my technological awakening, that has completely changed the direction of my career and my life. In the spirit of these futurists, I want to talk about why Web3 excites me just as much as their ideas, but is instead happening as we speak.

Why is Web3 So Exciting?

This post is meant to dive more into what I think are the benefits and repercussions of Web3. If you want to know my interpretation of what Web3 is, see my thoughts here.

Web3 represents a handful of ideas which together bring about entirely new mental models, organizational structures, and community incentives. These force us to rethink many things that we have become accustomed to.

All of the recent innovation happening is possible because of decentralized protocols. The internet itself has thrived because of native internet protocols that we use everyday, like HTTP, FTP, TCP, and SSH.

One of the reasons these protocols have been so successful was that they were widely adopted and not subject to change. If I build a site using HTTP, people can use it without any centralized intermediary – we can trust that it is going to work.

There are two major pieces of native functionality that have been left out up until recently – payments and state.

Blockchains have enabled both of these things, opening the door for programmable money and state without the need of a centralized server, bank, or any intermediary at all.

Web3 Enables Ownership

One of the driving forces and the one that resonates with most people (and me) is that Web3 enables ownership.

Gaming

At some point the internet and gaming became almost indistinguishable. Not only because most games continue to receive updates over time, but the most popular ones are often the most interactive ones.

Fortnite took a lot of people by surprise because it created an innovative new combination of gameplay, peer-to-peer connection, and a unique business model – and everyone gets the game for free.

The experience is very interactive, you can join old friends and make new ones, there are constant improvements and enhancements that just happen automatically – the game is consistently evolving.

The monetization strategy was also innovative. Fortnite allows players to buy in-game currency as well as skins that they can wear in the game. If you have a child you know that the $65 you may have spent on the game itself is probably peanuts compared to the amount of money kids spend over the lifetime of their gameplay.

The problem, though, is this: when the player decides to stop playing the game or outgrows it, where has all that money gone? More importantly, who is allowed as a creator to benefit from all of the purchasing power? The answer is, well, Fortnite (the platform).

What if, instead, players retained ownership of their items and were able to keep or sell them? Their items would maintain, increase, or decrease in value like any physical asset.

These types of experiences and communities are now being made possible via NFTs. NFTs enable scarcity in a world where there was in the past no scarcity.

Axie Infinity is an example of how this looks in practice. It is a blockchain-based game that is the most successful of its kind, and has recently had explosive growth, catapulting it to over $1 billion in sales with over $780 million in the 30 days ending August 10 2021.

Parallel is an online card game that has done over $100 million in sales and is still extremely early. Dark Forest enables players to get paid to play the game.

When players realize they can retain much of the value of their time and investments while still enjoying the benefit of the game, it changes the way they view gaming and where they spend their money. But it also aligns new incentives around the game itself. If the game succeeds, they can share in that success, therefore they become even more invested.

The combination of ownership, community, and creators who have built audiences creates a whirlwind of new and exciting opportunities that we are just starting to begin see explored.

Ryan Watt, the head of YouTube gaming agrees.

Social media and art

Social media platforms were revolutionary. They allowed anyone from almost any background the ability to grow and foster large audiences using tools that were made free to anyone with a device and an internet connection.

There are no gatekeepers to becoming famous on social media as there have been in the past in film and TV. The intermediary was abstracted away and peer to peer connections and content sharing was made possible.

The flaw in these implementations is that they offer a terrible monetization system, not just for the platform but for the creator as well.

Advertising and the exploitation of user data is the go to play. Also almost all of the money generated by the platform, goes to the platform – the platform monetizes the content being created by its users in exchange for use of the platform itself. This is how social media works today.

In Web3, both creators and the community are able to gain and retain ownership within a platform, creating a synergy that, once experienced, makes the legacy interactions of the past seem archaic and undesirable.

When I say ownership, I don't only mean ownership of content, but actual equity as well.

We are seeing the beginnings of this in the art world of Web3. Artists who were, in the past, often barely making it are now able to leverage their platforms, often in collaboration with other community members or causes. They can create projects that leverage NFT collections to give community members as well as the public a way to participate and distribute equity all around. Art and code are also beginning to overlap.

Projects like Generative Masks allow talented creators like Takawo Shunsuke to leverage the skills he's acquired throughout his career to generate over $3 million in sales for his collection in just a few minutes. He's able to spread awareness for himself and his cause, and create another new community (of owners) simultaneously.

The best part is that he's giving it all back to the communities he's benefited from. On top of that, smart contracts allow him to programmatically enable a commission for any future sale that happens going forward, and in just a couple of weeks that amounts to another $600,000.00+.

Generative art itself is an emerging category that combines code and creativity and is something that could alone warrant an entire post. But it suits the coming era particularly well, as it enables artists to scale their creativity, community, and distribution.

There will continue to be a larger and larger percentage of digital artists because they can use powerful tools and programs to create art that can then be used in an infinite number of ways. They can then put it for sale on an international, 24 hour, liquid market.

OpenSea, the top online art marketplace today, has seen an absolute explosion in growth the past few months.

Even recently surpassing Etsy in sales.

Whether this type of volume continues, I have no idea. My guess is that there will be some volatility and fairly large swings both up and down. But there is definitely something there.

Most of these NFT projects are launched on Ethereum. Ethereum is soon merging a new consensus mechanism that will make NFTs orders of magnitude more environmentally friendly as a means of sales and transfer of art, which in the past all required ground transportation.

Future of social media

As it stands today, users of social media platforms can begin leveraging Web3 tools, communities, and platforms to begin monetizing their audience.

I believe there will be a breakthrough app that will disrupt social media as we know it built in the in the next 1 - 3 years that blends all of these ideas together in a way that we haven't experienced yet.

Many people have echoed a similar sentiment. Aave, a very successful DeFi protocol built on Ethereum, has already begun work on a decentralized version of Twitter:

Jack Dorsey of Twitter is also working on a Decentralized version of Twitter, though I believe that this type of application will ultimately come from the community or a DAO.

DAOs, grants, community ownership, and social tokens

DAO stands for Decentralized Autonomous Organization. You can read about what a DAO is here, here, and here, but I want to focus on how DAOs will play a part in the new creator economy.

Shared ownership is a characteristic you'll see carried across all areas of Web3, including how we think about companies and incentive structures around how business is done.

In Web2 companies, cash usually comes from investors and there is no value returned to them for years. Ownership is largely concentrated in the first handful of employees along with their investors.

It usually takes years to reach a point where investors or employees with equity can begin to see any return on their investment and time spent, often through the old ways of advertising and exploitation of user data.

Web3 and blockchains bring about entirely new business models, made possible by tokenization and cryptoeconomic protocols.

There are quite literally countless ways that these tokens are being utilized to create new ways of collaboration and building, ranging from DAOs to web infrastructure to micro-economies:

PartyDAO which created over $200,000 in revenue in its first day, was "built in 3 months by a small group of internet friends working part-time", and is backed by a smart contract

Compound, a decentralized finance protocol that allows you to lend and borrow cryptocurrency without trusting a third party with your funds has a market cap of over $2 billion as of this writing

Super Rare is a digital art platform that recently launched a token, airdropping as much as $140,000 to its earliest users

Gitcoin is a platform that enables developers to get paid for working on open source projects

Graph Protocol is a decentralized web infrastructure protocol that allows developers to build APIs to enable the performant querying of blockchain data, all enabled by its native utility token

Seed Club is a social token incubator that’s focused on helping creators launch and grow social tokens

Friends with Benefits is a social DAO and community that I'm part of that is 100% owned and governed by the participants

PleasrDAO allows investors to come together to purchase high-value non-fungible tokens like this piece from Edward Snowden.

Most DAOs have desirable grants programs, enabling developers and other participants to work with various teams and projects at their will, on things they find interesting or that fit their skill set.

There are more and more people beginning to work full time for grants and with DAOs vs traditional full time employment.

Conclusion

If this sounds like something you're interested in being involved in, I'd suggest that you jump right in. Try P2E (play to earn), get involved with a DAO, or even mint your own NFT.

Also check out How to Get into Crypto, Ethereum, and Web3 as a Developer which is what I put together after getting my own start in the space.

If you want to learn more about these ideas, I encourage you to follow some of the people I mention in this post:

Also, here are some of my favorite articles that touch on some of the stuff I've outlined here:

The Rise of Micro-Economies

The Creator Economy: Today Vs. 2025

The Value Chain of the Open Metaverse

The DAO of DAOs

Thanks to Aditi for helping me with ideas and edits as I was getting this across the finish line 🙏

When you think about developing a decentralized application, a blockchain like Ethereum probably comes to mind.

Blockchain is fantastic for managing state, automating processes via Smart Contracts, and exchanging economic value.

You can follow this tutorial to learn blockchain by building one from scratch yourself if you want to learn more.

But where do you store your application's content? Images? Videos? The application's website front-end composed of all the HTML, CSS, and JS files? Are your application and your users' content loaded from a centralized AWS server?

Storing the content on the blockchain would be expensive and inefficient.

Your blockchain application needs decentralized storage!

In this tutorial, I will introduce you to the InterPlanetary File System, or IPFS. You will learn:

1. How to store and retrieve content from a decentralized storage
2. How to run your IPFS node
3. All about the low-level internals of the IPFS protocol
4. And we'll read a Wikipedia website stored on IPFS

Ready? Let's go.

Table of Contents

• What is the IPFS?
• How to setup an IPFS node
• How to store and retrieve IPFS content using the CLI and HTTP
• What is CID – the IPFS content-based identifier
• How to reverse engineer the IPFS datastore
• How to connect an IPFS node to a decentralized network
• How to exchange data using the peer-to-peer Bitswap protocol
• How to persist content from the peer-to-peer network

What is the IPFS?

The InterPlanetary File System, or IPFS for short, is a peer-to-peer hypermedia protocol designed to make the web faster, safer, and more open.

IPFS is a protocol for storing and sharing content. As in the blockchain world, every user is running its node (server). The nodes can communicate between each other and exchange files.

What is unique about IPFS?

First of all, the IPFS is decentralized because it loads the content from thousands of peers instead of one centralized server. Every piece of data is cryptographically hashed, resulting in a safe, unique content identifier: CID.

Store your website in IPFS to avoid censorship and a single point of failure. Your personal IPFS node goes offline? Don't worry, the website will still load from other nodes across the globe serving it.

For example, suppose your government bans Wikipedia. In that case, you can still access a decentralized version of Wikipedia indexed on April 17th by loading it from the IPFS peer-to-peer network persisted under CID:

"QmT5NvUtoM5nWFfrQdVrFtvGfKFmG7AHE8P34isapyhCxX"

Second, the integrity of IPFS content can be cryptographically verified.

And finally, the IPFS content is de-duplicated. If you tried storing two identical 1MB files in the same IPFS node, they would be stored only once, eliminating the duplication, because their hash would produce an identical CID.

How to Setup an IPFS Node

Install IPFS

Open the official IPFS docs installation page and follow the instructions depending on your operating system (Windows, macOS, Linux). I will be documenting the Ubuntu installation process below.

I prefer compiling the ipfs/go-ipfs repository from scratch to debug the code when needed, and let's be honest: GoLang rocks.

Compile the codebase in Go

Clone the repository and run the install script in the Makefile.

git clone https://github.com/ipfs/go-ipfs.git
cd go-ipfs
git checkout v0.8.0-rc2
make install

Or download pre-compiled IPFS:

sudo snap install ipfs

Validate the installation

Let's be honest. Go is amazing and compiling the codebase yourself is bad-ass and decentralized. The resulted binary will be created in your $GOPATH.

which ipfs
> /home/web3coach/go/bin/ipfs

ipfs version
> ipfs version 0.8.0-rc2

Initialize a new node

Run ipfs init to create your new node. By default, it will create a folder and store all the data in ~/.ipfs You can tweak this by configuring the IPFS_PATH ENV variable.

IPFS_PATH=/home/web3coach/.ipfs_tutorial ipfs init

> generating ED25519 keypair...done
> peer identity: 12D3Koo...dNs
> initializing IPFS node at /home/web3coach/.ipfs_tutorial

Your node is now fully initialized, awaiting your content.

How to Use IPFS

Add content

IPFS can handle all kinds of different data types – from simple strings to images, videos, and websites.

Start by storing a short message hello IPFS world by Web3Coach:

echo "hello IPFS world by Web3Coach. BTW: Ethereum FTW" | ipfs add

The content is now stored and indexed by a cryptographic hash function returning its unique content identifier (CID):

> added QmRBkKi1PnthqaBaiZnXML6fH6PNqCFdpcBxGYXoUQfp6z
> 49 B / 49 B [========] 100%

Your IPFS node will generate the same CID on your local file system as in this tutorial. That's because IPFS hashes the content and returns its unique fingerprint, and as we know, a secure hash function will always return the same output given the same input.

Pin content

When you add content, you add it ONLY to your local node. The content does NOT automatically replicate across the entire network – this is a common confusion between IPFS users and developers.

When you store content via the add command, IPFS will also execute the pin command by default:

ipfs pin add QmRBkKi1PnthqaBaiZnXML6fH6PNqCFdpcBxGYXoUQfp6z

To replicate content, you must take your node online, join the p2p network, and pin the specific CID from another node. You will learn how to do this further in the tutorial and find out what happens in the background.

Read content

Copy-paste the CID to IPFS cat command to read it from disk:

ipfs cat QmRBkKi1PnthqaBaiZnXML6fH6PNqCFdpcBxGYXoUQfp6z
> hello IPFS world by Web3Coach. BTW: Ethereum FTW

The add , pin and cat commands are the most significant IPFS functions, and you just learned them. Congrats, well done!

How IPFS Content Addressing Works

What is QmRBkKi1PnthqaBaiZnXML6fH6PNqCFdpcBxGYXoUQfp6z?

It’s a self-describing content-based identifier.

What does "self-describing" actually mean? It means that by splitting the string following the IPFS specification, you will know everything you need to know about the data it indexes.

• what CID version it is
• how to read the CID string (base32? base58? hex?)
• how data is encoded
• what hash function fingerprinted the data
• the hash function's length

The IPFS team built a convenient website for analyzing a CID:

By parsing the QmRBkKi1P…p6z CID, you discover:

• the CID follows version 0 spec because it starts with Qm
• the QmRBkKi1P…p6z string is encoded using base58btc
• the data "hello IPFS world by Web3Coach. BTW: Ethereum FTW" were encoded as DAG Protobuf under a codec 0x70 before being stored on disk
• the hash code 0x12 signals the data fingerprint obtained using the sha256 hash function, producing a unique 32 byte long digest

"Slightly more complicated" than a simple auto-increment INT in a MySQL table... but extraordinarily potent and future proof. Let me explain.

CID Versions

There are currently two CID versions: v0 and v1.

The CID v0 is not flexible and limited to:

• start with characters "Qm"
• where the CID string is encoded using base58btc
• the data is encoded with dag-pb by default
• can be converted to CID version 1, but not the other way around

The CID v1 leverages several prefixes for maximum interoperability:

CID v1 = Multibase + Multicodec + Multihash

In another words, parsing the binary into a CID v1 string follows this spec:

<base><codec><hash-function><hash-length><hash-digest>

Multihash

To be future-proof and enable different hashing algorithms, IPFS created the following standard:

CODE : SIZE : DIGEST

type DecodedMultihash struct {
   Code   uint64 // 0x12
   Name   string // sha2-256
   Length int    // 32 bytes
   Digest []byte // Digest holds the raw multihash bytes
}

Multihash has many advantages. When computers are more powerful in 5 years, you could use a stronger hash function like sha3-512 as long as you configure the corresponding 0x13 code as the Multihash in the CID prefix – the protocol will be ready to handle it.

Multicodec

The Code attribute tells you how data is encoded before being stored on disk, so you know how to decode it back when the user wants to read it. It could be anything CBOR, Protobuf, JSON…

IPFS maintains a public list of all possible codecs. The most common codecs are:

raw       | ipld      | 0x55 | raw binary
dag-pb    | ipld      | 0x70 | MerkleDAG protobuf
dag-cbor  | ipld      | 0x71 | MerkleDAG cbor

// but you could also encode Ethereum blocks on IPFS!
eth-block | ipld      | 0x90 | Ethereum Block (RLP)

Multibase

The problem with CID v0 and the base58btc encoding is the lack of interoperability between environments. A multibase prefix adds support for different encodings like base32 to achieve DNS-friendly names.

A table with all Multibase encodings:

encoding  | code
base32    | b
base58btc | z
base64    | m

You spot a Multibase encoding based on the first character:

QmRBkKi1PnthqaBaiZnXML6fH6PNqCFdpcBxGYXoUQfp6z

• is CID v0
• the CID string is encoded with base58btc

bafybeibkjmxftowv4lki46nad4arescoqc7kdzfnjkqux257i4jonk44w4

• CID v1
• the CID string is encoded with base32

Both CID versions can retrieve the same content because after you strip the encoding, it's the Multihash that indexes the blocks on the datastore level. In contrast, Multibase is only used to pass the CID correctly in different environments (CLI, URL, DNS).

ipfs cat QmRBkKi1PnthqaBaiZnXML6fH6PNqCFdpcBxGYXoUQfp6z
> hello IPFS world by Web3Coach. BTW: Ethereum FTW

// equivalent to
ipfs cat bafybeibkjmxftowv4lki46nad4arescoqc7kdzfnjkqux257i4jonk44w4
> hello IPFS world by Web3Coach. BTW: Ethereum FTW

Phew. Things got "slightly complex" very quickly.

Speaking of complicated topics, IPFS is powerful because it doesn't treat content as just "data" but as data structures – specifically InterPlanetary Linked Data structure: IPLD. In short, you can implement any file-system, database, or structure on top of IPLD.

For example, you can store all Ethereum blocks on IPFS as long as you set eth-block and eth-tx codecs and register an appropriate Decoder when working with the IPLD graph.

Let's dig into it and explore the default IPLD structure with the DAG Protobuf codec.

How IPFS Stores Content on the File-system

“The ipfs add command will create a Merkle DAG out of the data following the UnixFS data format. Your content is broken down into blocks using a Chunker, and then arranged in a tree-like structure using 'link nodes' to tie them together. The returned CID is the hash of the root node in the DAG.”

Confused?

Rolling back to basics.

Let's explore the node’s data directory

At the beginning of this tutorial, when you initialized your IPFS node with the ipfs init command, you generated the following directory:

export IPFS_PATH=/home/web3coach/.ipfs_tutorial
cd $IPFS_PATH
~/.ipfs_tutorial  tree

.
├── blocks
│   ├── 6Y
│   │   └── CIQA4XCGRCRTCCHV7XSGAZPZJOAOHLPOI6IQR3H6YQ.data
├── config
├── datastore
│   ├── 000002.ldb
│   ├── 000003.log
│   ├── CURRENT
│   ├── CURRENT.bak
│   ├── LOCK
│   ├── LOG
│   └── MANIFEST-000004
├── datastore_spec
├── keystore
└── version

From a very high-level point of view:

• blocks — IPFS stores all the chunked data here, although the go-ipfs flexible interfaces allow you to swap the storage implementation for a different database
• config — Node’s settings (file-system, identity, specs, networking)
• datastore — Indexing and other logic

Don't take my word for it. Create a new file with the following content on your local file system and then add it to IPFS:

hello IPFS world by Web3Coach. Testing DAGs
hello IPFS world by Web3Coach. Testing DAGs
hello IPFS world by Web3Coach. Testing DAGs

ls -la hello_world.txt
> 131 bytes hello_world.txt

ipfs add hello_world.txt
> added QmNtQtxeavDXTjCiWAAaxnhKK3LBYfFfpXUXjdMDYXwKtH

Reverse engineering the go-ipfs codebase, this is what is happening behind the scenes:

IPFS UnixFS adding a new file and converting it to a block

Validate the persistence process by inspecting the blocks directory. You will find the content was written under the Multihash Datastore Key using DAG Protobuf encoding (131 bytes + Protobuf extra encoding).

ls -la blocks/PV/
> 142 CIQAQIXXW2OAQSKZ6AQ2SDEYRZXWPDZNJUAFR3YORYN75I5CQ3LHPVQ.data

vim blocks/PV/CIQA...
<8b>^A^H^B^R<83>^Ahello IPFS world by Web3Coach. Testing DAGs
hello IPFS world by Web3Coach. Testing DAGs
hello IPFS world by Web3Coach. Testing DAGs^X<83>^A

To interact with your raw content, use the ipfs object command.

ipfs object get QmNtQtxeavDXTjCiWAAaxnhKK3LBYfFfpXUXjdMDYXwKtH | jq

{
  "Links": [],
  "Data": "\b\u0002\u0012�\u0001hello IPFS world by Web3Coach. Testing DAGs\nhello IPFS world by Web3Coach. Testing DAGs\nhello IPFS world by Web3Coach. Testing DAGs\u0018�\u0001"
}

• Because the content is only 131 bytes, it fits to one DAG Node
• The Dag Node is persisted as one Block on disk
• The DAG Node has zero links to other Nodes

Time to experiment.

Add the same file again, but configure the Chunker to 64 bytes (or use a bigger file, but a smaller Chunker will demonstrate the concept better).

ipfs add --chunker=size-64 hello_world.txt

> 131 bytes QmTwtTQgrTaait2qWXYjTsEZiF4sT7CD4U87VqQ27Wnsn8

You get a new CID!

IPFS split the content into 4 DAG Nodes and wrote 4 Blocks with data encoded in DAG Protobuf format to disk.

IPFS splits a file into multiple chunks (DAG Nodes + Blocks)

ipfs object get QmTwtTQgrTaait2qWXYjTsEZiF4sT7CD4U87VqQ27Wnsn8 | jq

{
  "Links": [
    {
      "Name": "",
      "Hash": "QmTbsuUYzy3nT6NApb5t7VUq3iQKZXrJJJY2j1miMVgaJU",
      "Size": 72
    },
    {
      "Name": "",
      "Hash": "QmNy9iFF8uU1Cn7trxpSgqxMsjmi4zQ7xgyEgsWff5rnfH",
      "Size": 72
    },
    {
      "Name": "",
      "Hash": "QmdEitCfYgBNxLhxTNvdLaDmTypSAWkGErjw33VZxUbWK3",
      "Size": 11
    }
  ],
  "Data": "\b\u0002\u0018�\u0001 @ @ \u0003"
}

The ultimate test is to retrieve each DAG Node's data and verify the text is split into three chunks:

DAG Protobuf Node 1:

ipfs object get QmTbsuUYzy3nT6NApb5t7VUq3iQKZXrJJJY2j1miMVgaJU | jq

{
  "Links": [],
  "Data": "\b\u0002\u0012@hello IPFS world by Web3Coach. Testing DAGs\nhello IPFS world by \u0018@"
}

DAG Protobuf Node 2:

ipfs object get QmNy9iFF8uU1Cn7trxpSgqxMsjmi4zQ7xgyEgsWff5rnfH | jq

{
  "Links": [],
  "Data": "\b\u0002\u0012@Web3Coach. Testing DAGs\nhello IPFS world by Web3Coach. Testing D\u0018@"
}

DAG Protobuf Node 3:

ipfs object get QmdEitCfYgBNxLhxTNvdLaDmTypSAWkGErjw33VZxUbWK3 | jq

{
  "Links": [],
  "Data": "\b\u0002\u0012\u0003AGs\u0018\u0003"
}

What’s the benefit of splitting the content into multiple chunks and use content-addressing and CIDs?

• Data deduplication
• Decentralization

Next time you want to store a file that would share part of the content with another file, IPFS wouldn't store a duplicate block! It would instead link to an already existing DAG Node and only store the new, unique chunks.

Converting content to a directed acyclic graph with many nodes also helps to load the content in parallel. For example, a blog post, image, entire Wikipedia website can load from multiple IPFS peer nodes. Your node then verifies the integrity of received blocks by re-hashing all the data content and asserting the constructed CID.

You've now learned the bread and butter of IPFS – excellent progress!

One more critical component left: Networking.

How to Connect an IPFS Node to the p2p Network

Every node has its config file generated during the ipfs init execution.

Open it.

vim $IPFS_PATH/config

Other settings aside, you find your node’s Identity (PeerID + Private Key):

"Identity": {
    "PeerID": "12D3KooWCBmDtsvFwDHEr...",
    "PrivKey": "CAESQCj..."
  },

And a list of Bootstrap addresses:

"Bootstrap": [
    "/dnsaddr/bootstrap.libp2p.io/p2p/QmcZf59b...gU1ZjYZcYW3dwt",
    "/ip4/104.131.131.82/tcp/4001/p2p/QmaCpDMG...UtfsmvsqQLuvuJ",
    "/ip4/104.131.131.82/udp/4001/quic/p2p/Qma...UtfsmvsqQLuvuJ",
    "/dnsaddr/bootstrap.libp2p.io/p2p/QmNnooD5...BMjTezGAJN",
    "/dnsaddr/bootstrap.libp2p.io/p2p/QmQCU2Ec...J16u19uLTa",
    "/dnsaddr/bootstrap.libp2p.io/p2p/QmbLHAnM...Ucqanj75Nb"
  ],

You connect to other peers in the IPFS network by running the ipfs daemon command. Your node will first establish a p2p connection with Protocol Labs (company behind IPFS) bootstrap nodes, and through these bootstrap nodes, you will further find hundreds of other peers.

ipfs daemon 

> Initializing daemon...

Swarm listening on /ip4/127.0.0.1/tcp/4001
Swarm listening on /ip4/127.0.0.1/udp/4001/quic
Swarm listening on /ip4/172.17.0.1/tcp/4001
Swarm listening on /ip4/172.17.0.1/udp/4001/quic
Swarm listening on /ip4/192.168.0.142/tcp/4001
Swarm listening on /ip4/192.168.0.142/udp/4001/quic
Swarm listening on /ip6/::1/tcp/4001
Swarm listening on /ip6/::1/udp/4001/quic
Swarm listening on /p2p-circuit
Swarm announcing /ip4/127.0.0.1/tcp/4001
Swarm announcing /ip4/127.0.0.1/udp/4001/quic
Swarm announcing /ip4/192.168.0.142/tcp/4001
Swarm announcing /ip4/192.168.0.142/udp/4001/quic
Swarm announcing /ip4/88.212.40.160/udp/4001/quic
Swarm announcing /ip6/::1/tcp/4001
Swarm announcing /ip6/::1/udp/4001/quic

API server listening on /ip4/127.0.0.1/tcp/5001
WebUI: http://127.0.0.1:5001/webui

Gateway (readonly) server listening on /ip4/127.0.0.1/tcp/8080
Daemon is ready!

Keep in mind, that by running the IPFS Daemon:

1. Your node connects to the p2p net and can exchange blocks with other nodes
2. Other peers can access the content on your node – as long they know the CIDs
3. Peers will talk to you through TCP, UDP on port: 4001
4. If you have an application, start storing and consuming your node's content via the HTTP API listening on port: 5001.

For application development, I recommend the official ipfs-http-client library in JS exposing all the core commands – add, cat, object and others. It will speed up your coding progress.

I will use curl to interact with the API to keep this tutorial "short."

How to use the IPFS HTTP API:

Add content: :5001/api/v0/add

curl -X POST -F file=@/home/web3coach/go/src/github.com/ipfs/go-ipfs/hello_world.txt "http://127.0.0.1:5001/api/v0/add"

{"Name":"hello_world.txt","Hash":"QmNtQtxeavDXTjCiWAAaxnhKK3LBYfFfpXUXjdMDYXwKtH","Size":"142"}

Read content: :5001/api/v0/cat

curl -X POST "http://127.0.0.1:5001/api/v0/cat?arg=QmNtQtxeavDXTjCiWAAaxnhKK3LBYfFfpXUXjdMDYXwKtH"

hello IPFS world by Web3Coach. Testing DAGs
hello IPFS world by Web3Coach. Testing DAGs
hello IPFS world by Web3Coach. Testing DAGs

See the official HTTP API docs for the complete list of available commands.

How to peer with other IPFS nodes

Fun experiment. Use the ipfs swarm command and check how many nodes you already discovered:

ipfs swarm peers

> 
/ip4/85.70.151.37/tcp/4001/p2p/QmSuCtR...aPq6h4AczBPZaoej
/ip4/91.121.168.96/udp/54001/quic/p2p/QmeC7H...8j2TQ99esS
...
...
...

ipfs swarm peers | wc -l
> 186

Bravo! You are connected to 186 peers forming an unstoppable peer-to-peer web.

What about privacy?

Other peers can access all the content you add to your IPFS node. There is no built-in privacy mechanism, so never add unencrypted, sensitive/personal content to IPFS!

How Nodes Exchange Data Using the Bitswap Protocol

So far, you only interacted with your local content. Imagine you live in a place where the local government decided to block access to Wikipedia. No bueno.

Fortunately, because someone added all the Wikipedia content to IPFS, you can run your node and access its knowledge by requesting the content from peers across the globe.

http://localhost:8080/ipfs/QmT5NvUtoM5nWFfrQdVrFtvGfKFmG7AHE8P34isapyhCxX/wiki/Anasayfa.html

The DAG Service will check the blocks in your datastore, but it won’t find any for QmT5NvUtoM5nWFfrQdVrFtvGfKFmG7AHE8P34isapyhCxX.

The node will therefore create a network request to its peers using the Bitswap protocol via exchange component:

func getBlock(ctx context.Context, c cid.Cid, bs blockstore.Blockstore, fget func() exchange.Fetcher) (blocks.Block, error) {
   err := verifcid.ValidateCid(c) // hash security
   if err != nil {
      return nil, err
   }

   block, err := bs.Get(c)
   if err == nil {
      return block, nil
   }

   if err == blockstore.ErrNotFound && fget != nil {
      f := fget() // Don't load the exchange until we have to

      log.Debug("Blockservice: Searching bitswap")
      blk, err := f.GetBlock(ctx, c)

Internally, the CID is added to a Wantlist :

// Wantlist is a raw list of wanted blocks and their priorities
type Wantlist struct {
   set map[cid.Cid]Entry
}

// Entry is an entry in a want list, consisting of a cid and its priority
type Entry struct {
   Cid      cid.Cid
   Priority int32
   WantType pb.Message_Wantlist_WantType
}

And the PeerManager will iterate over known peers and their peers until it finds an online node capable of providing the wanted Block:

// PeerManager manages a pool of peers and sends messages to peers in the pool.
type PeerManager struct {
   pqLk sync.RWMutex

   peerQueues map[peer.ID]PeerQueue
   pwm        *peerWantManager

   createPeerQueue PeerQueueFactory
   ctx             context.Context

   psLk         sync.RWMutex
   sessions     map[uint64]Session
   peerSessions map[peer.ID]map[uint64]struct{}

   self peer.ID
}

The result?

You can consume the forbidden fruits from Wikipedia directly from localhost:8080:

IPFS loading Wikipedia on your local node

Uncensorable, decentralized storage :)

How to Persist Content from the p2p Network

You must know a crucial thing about IPFS: the content you access from the network will be garbage collected unless you pin it.

Pinning and Garbage Collection

At the beginning of the article you learned that content added to your node via the ipfs add command or its HTTP equivalent is pinned by default.

ipfs pin ls | grep QmNtQtxeavDXTjCiWAAaxnhKK3LBYfFfpXUXjdMDYXwKtH
> QmNtQtxeavDXTjCiWAAaxnhKK3LBYfFfpXUXjdMDYXwKtH recursive

Pinned blocks are marked as NOT TO BE DELETED when the Garbage Collection runs.

Why would the Garbage Collection delete some blocks? To keep your node healthy by controlling its storage size.

By reading Wikipedia or by accessing any other content from the p2p network, IPFS downloads its blocks. As the node's datastore grows in size, a periodic garbage collection process will prune unpinned blocks, so you don't run out of disk space.

If you want your content to be accessible 24/7 on the IPFS network, I recommend that you use a reliable remote provider to pin it: Infura - is the easiest way to get started, and you get 5GB free of decentralized storage.

Follow the getting started docs.

How to pin Wikipedia locally

Verify that the Wikipedia root-level CID (highest DAG node) isn't yet pinned on your node:

ipfs pin ls | grep QmT5NvUtoM5nWFfrQdVrFtvGfKFmG7AHE8P34isapyhCxX
> no output, not pinned

IPFS stores specific versions of Wikipedia in the form of a DAG. I recommend inspecting its graph before pinning:

ipfs object get QmT5NvUtoM5nWFfrQdVrFtvGfKFmG7AHE8P34isapyhCxX | jq

{
  "Links": [
    {
      "Name": "0C-",
      "Hash": "QmSEwJo8Z5bqVX3AhocyimJzPWetr7HgbWbwCg6zbp43AP",
      "Size": 1248085
    },
    {
      "Name": "43I",
      "Hash": "QmPW3kRjncDj145bP9DVNc791FowLPwYHnqbTzfe3whdyZ",
      "Size": 2611324931
    },
    {
      "Name": "58wiki",
      "Hash": "QmRNXpMRzsTHdRrKvwmWisgaojGKLPqHxzQfrXdfNkettC",
      "Size": 12295304394
    },
    {
      "Name": "92M",
      "Hash": "Qmbcvk7jpBTUKdgex139Nvv7BrKocE3pQVKhNJtTU77Qv5",
      "Size": 793
    },
    {
      "Name": "A0index.html",
      "Hash": "QmNqbYogAxH4mmt5WhuKN7NFEUDZ9V3Scxh7QbLwTKBJDk",
      "Size": 191
    }
  ],
  "Data": "\b\u0005\u0012\u0015\u0001\u0000\u0004\u0000\u0000\u0000\u0000\u0000\u0000\u0001\u0000\u0000\b\u0000\u0000\u0000\u0000\u0000\u0000\u0010\u0000(\"0�\u0002"
}

The root DAG object has five links. Four links are relatively small, but one link points to a DAG node with a total size of 12GB. If you inspect this DAG node, you will see 256 more links and a total cumulative (recursive) size of 12GB.

ipfs object stat QmRNXpMRzsTHdRrKvwmWisgaojGKLPqHxzQfrXdfNkettC

NumLinks:       256
BlockSize:      12075
LinksSize:      12034
DataSize:       41
CumulativeSize: 12295304394

Every node with an important pinned article, video, documentary, or a cat meme makes the web more accessible, antifragile, decentralized, and robust.

ipfs pin add QmT5NvUtoM5nWFfrQdVrFtvGfKFmG7AHE8P34isapyhCxX

The pinning process will recursively traverse the entire DAG node, fetch all its links from the Bitswap protocol and then pin every single Block to your local datastore.

Congratulations! In this article, you learned how decentralized storage works behind the scenes.

I worked 47 hours to write this blog post… but you can re-tweet it in just 5 seconds:

Lately, I've been talking about my move into the Web3, Ethereum, and crypto space since making the switch from a traditional web, mobile, and cloud background.

Since making that move, a shocking number of people have reached out to me who are also thinking about doing the same.

It's really great to see so many other people interested in these fields. And if I'm being honest – it feels validating to know that so many others are also on the fence and are so deeply interested in the space as well.

As for me, I was nervous about making the career switch. Moving into a completely new area of specialization, with a technology I was still getting ramped up on, and a community I was not yet involved with, was a big leap. Especially compared to a very comfortable role with a FAANG company that paid really well (and a team that I really loved).

After over a month, I have zero regrets with the change. I'm also the happiest I've been in a long time, and am excited and energized about the things I have the opportunity to work on everyday.

I decided to write this post to give a blueprint for anyone looking to get into blockchain, crypto, Ethereum, and Web3 from a traditional development background. I can point people to this blog post the next time I get asked how to get into the space.

I'll break this article up into a few main parts:

1. Technologies and resources to learn
2. Tradeoffs and considerations
3. People to follow
4. Companies hiring and doing interesting stuff
5. General tips and landing a job

Let's dive in.

Technologies and Resources to Learn About Ethereum and Blockchain

What I'm most interested in is usually a function of where I predict technology will be in the near future and where I see the current momentum being. So that's what I will focus on here (and this is what I am doing personally).

To me, the most exciting parts of this space are decentralization, DeFi, governance / DAOs, and decentralized web infrastructure.

Because of this, I'm focusing on both Ethereum development and Solidity. With the Solidity programming language ,you can program smart contracts for Ethereum as well as for many other EVM compatible blockchains.

As of this writing, Ethereum also has the powerful and important combination of momentum, developer mindshare, and existing production dapps.

Ethereum is also currently moving to a new consensus mechanism, proof of stake. This addresses the environmental concerns I used to have about how cryptocurrency works at a core level.

Once you learn how everything works fundamentally, I encourage you to then check out other blockchains and projects outside of Ethereum and EVM.

This will give you a better understanding of the industry as a whole. It will also help you see if there are other projects that attract you or that you believe are better approaches to achieving the goal that is Web3.

Consider looking into Solana, Polkadot, Near, Avalanche or Cosmos.

To get started learning blockchain development with Ethereum and Solidity, I suggest you do the following:

1. Read the Ethereum docs

Scan through the Ethereum docs. Be sure to check out the section Intro to Ethereum as well as anything else that catches your eye.

Also be sure to check out the dapp showcase to get a good understanding of the successful apps being built and used in the current ecosystem.

2. Read the Solidity documentation

The Solidity docs are a really good place to get started, especially solidity by example. This gives you a few examples of popular smart contracts like voting, an auction, remote purchase, and micropayments.

You can copy and paste these contracts in the Remix IDE to start executing and modifying them to see how they work.

I also did a video walkthrough of the voting contract here.

3. Get comfortable with the Remix IDE

It's really easy to play around with and start building smart contracts without having to set up any type of development environment by using the Remix IDE. It's part of the Remix Project which is funded by the Ethereum Foundation.

This Remix IDE allows you to create, edit, and execute smart contracts directly from your browser. It offers a perfect environment for learning how solidity works. It's also great for building out various types of smart contracts and playing around with them as you are learning both solidity and how to interact with Ethereum

4. Try building out a full stack dapp

In addition to Solidity, the other parts of the the development stack include a local Ethereum environment like Hardhat or Truffle, a wallet like Metamask, as well as a client-side library that allows you to interact with the blockchain, like either Ethers.js or Web3.js.

To understand how all of this all fits together, it's useful to build out a full stack dapp on this stack from scratch. You can set up the front end project as well as the local development environment and deploy, run, and interact with a smart contract on the blockchain.

Here are two introductory courses to get you going with this:

1. Ethereum Programming Tutorial - DeFi, Solidity, Truffle, Web3.js
2. The Complete Guide to Full Stack Ethereum Development (and here it is in article form, too)

5. Consider reading these books

The space itself moves very quickly, so technical books often get out of date just as quickly. The fundamentals of what Web3 is, though, have not changed much at all.

There are a few really great books that helped me not only grasp the current state of everything, but that also helped open my eyes to the future possibilities and opportunities that lie within it.

Token Economy - How the Web3 reinvents the internet

If you only read one of these books, this is the one I'd say is the most important. It is a masterful deep dive into all of the shortcomings of the web as we know it, what Web3 aims to be, how it will affect various parts of our lives as we know it, and what needs to happen for this vision to be realized.

You can view the book here.

The Infinite Machine - How an Army of Crypto-hackers Is Building the Next Internet with Ethereum

This is the amazing story of how Ethereum came to be, walking you through the history of it all. It is a very thorough and entertaining account of the origin story of Ethereum, I highly recommend checking it out.

You can view the book here.

New Village - Power Back to People

This is a really cool story of how blockchain technologies and decentralization will affect the future of the world.

You can view the book here

How to DeFi

As you can probably tell by the title, this book focuses on how you can start using DeFi today. It gives you a good understanding about how you can use it today as well as some applications of it that we will see at some time in the future.

You can view the book here

The Spatial Web

The Spatial Web is a book that explores the future of the web and all of the implications, not only of Web3 and decentralization, but how everything will come together to enable things that we may have not yet considered.

It does a good job weighing the positive and negatives as well as ways that we may be able to address any negative outcomes of what is to come.

You can view the book here

And here are a couple of solidity books:

• Hands-On Smart Contract Development with Solidity and Ethereum
• Mastering Ethereum

6. Listen to these podcasts

Here are some good podcasts:

• Founders of Web 3 – The people that are creating and building the next phase of the internet.
• Bankless – The Ultimate Guide to Crypto Finance
• Into the Ether – Podcast about Ethereum
• Crypto 101
• Epicenter – Learn about Crypto, Blockchain, Ethereum, Bitcoin and Distributed Technologies

7. Watch these YouTube channels

• Ethereum Foundation
• Eat the Blocks – Short videos on blockchain development
• Finematics – Sharing interesting DeFi videos
• Dapp University – Videos in the Ethereum space
• BlockGeeks – General Blockchain Training
• The Daily Gwei
• Austin Griffith

I've also begun doing videos and tutorials on Ethereum and Solidity, so consider checking out my YouTube channel.

Tradeoffs and Considerations of Switching Careers

There are always things to consider when making a career transition, but especially when considering this space.

There are a lot of positives, but there are also unknowns as well as negatives. Let's talk about some of them.

It's nascent tech

While there are many existing dapps and companies already flourishing, this space is very much still coming into existence in many ways.

There are a lot of problems that we still need to solve, and there are no clear answers for many questions you'll have. The problems being solved are often complex, sometimes combining one or more aspects of distributed systems, game theory, cryptography, economics, social and political science, identity, psychology, and more.

Because of this, there are still things that we cannot yet build with the existing solutions that are available.

I personally think this is one of the more exciting things about all of it it, but it's not for everyone.

It's a volatile space

Many of the projects are built around various types of tokens. The value of many of these tokens rises and falls dramatically, and you often see that people gain and lose excitement in the entire space based on these swings.

If you haven't fundamentally bought into the ideas behind decentralization itself, you may find these ups and downs mentally taxing.

It's full of speculation

Because a lot of people only buy into certain tokens in a speculative way, it attracts some people who are in it only for the money.

You see things like scammers trying to get over on people and steal their money, endless talk about price swings from people who are speculating, and outright scam projects that often discredit the industry as a whole.

This is an annoying part of it and I don't really see it going away anytime soon.

This thread

I would also check out this Twitter thread. Although I have not experienced all of these things, he is definitely shining a light on some of the things I have seen.

General Tips and How to Land a Blockchain or Crypto-Related Job

There are many areas within the space that you can focus on and provide a positive impact on a team. I'd look into the different areas like governance, DeFi, NFTs, and decentralized web protocols to see what interests you the most and then focus on that.

There are a lot of opportunities and a lot of ways to stand out and get noticed. If you find an interesting project and would like to get involved, jump right into their community and ecosystem and start learning. Then see where you may be able to help out. Join their Discord or look at their GitHub issues to find ways that you can contribute.

This will give you an opportunity to meet people involved in the project and will open up discussions for potentially landing a role with them. In fact, it is very common for people within the teams to take notice of active community participants, they will then often reach out and try to recruit you without you even applying.

The pay is usually good. Depending on where you are coming from, it could be more or less, but it's probably not going to be at the high levels of what you see at FAANG companies.

There is probably more potential upside. Most companies offer a combination of base pay + equity in the form of their digital token, so if you stick around and can help make the project successful and the value of the token goes up, you can often make more than what you would in many other areas.

People to follow on Twitter

Here are a few people who you may consider following on Twitter:

Vitalik
Ashleigh Schapp
Arthur Hayes
Stani Kulechov
Gloria Kimbwala
Niran Babalola
Ric Burton
Dennison Bertram
Mana Silvora
Austin Griffith
Santiago Palladino
Zaki Manian
Anthony Sassano

I also found this comprehensive list created by someone on Twitter.

A few people on my team at Edge & Node:
Yaniv Tal
Tegan Kline
Eva Beylin
Adam Fuller
Brandon Ramirez

Teams doing interesting stuff (and hiring)

Compound
Uniswap
Chainlink
Skynet Labs
Aave
Matic
Livepeer
Consensys
ENS
OpenZeppelin
Foundation
Zora
Synthetix
Digital Currency Group

You can also find a pretty decent list of job opportunities in cryptocurrency here.

Also, my team at Edge & Node is hiring!

Conclusion

Did I mention this space is volatile? Be ready for some high highs and low lows, but also for some of the most fun you may have in your career.

You'll be working alongside some of the smartest people in tech trying to solve some of the most complex problems that I think will ultimately have a massive positive impact on humanity.