Building a Decentralized Chat App using Calimero and BOS: Step-by-Step Guide

In this guide, we will walk you through the step-by-step process of creating a decentralized chat application using Calimero and BOS, the Blockchain Operating System. Before delving into the technical details, let's understand what BOS is all about.

What is BOS (Blockchain Operating System)?

BOS, short for Blockchain Operating System, simplifies the development, deployment, and access of decentralized frontends. It serves as a gateway to the world of Web 3.0, with a strong emphasis on community-driven development.

Why Use BOS?

BOS serves as both a development environment and a social network, where users can deploy and explore new applications. Here's why BOS stands out:

1. Accessibility: BOS empowers users to locally run blockchain applications, ensuring robustness and censorship resistance while keeping the user experience smooth.

2. Security: All components' code resides on the blockchain, making it auditable and transparent. Users can confidently run the full stack locally.

3. Composability: BOS encourages developers to reuse and remix components, simplifying development. You can deploy new front-ends for smart contracts on the mainnet in under 10 minutes.

4. Chain Agnosticism: BOS is flexible and compatible with various blockchains, making it an ideal choice for developers working in multi-chain environments.

The Three Pillars of BOS

Now that we've scratched the surface of what BOS is, let's dig deeper into its workings, which are built on three fundamental pillars:

1. Components: These are composable frontends that address specific problems. Components are small web 3 applications stored entirely on-chain. Developers can fork and combine them to create full-fledged web applications.

2. Blockchains: Components can interact with any blockchain, with current support for all EVM chains (e.g., Polygon, zkSync) and NEAR. NEAR is chosen for cost-effective storage of HTML/CSS/JS.

3. Gateways: These gateways enable decentralized front-ends to be accessed by a broader audience. They consist of specialized virtual machines that load and execute frontends for various protocols, including Ethereum, Layer 2 solutions, and NEAR. The code for these frontends is stored on the NEAR blockchain.

Calimero X BOS Integration

The integration of BOS and Calimero accelerates front-end development for both projects. Calimero's private blockchain characteristics ensure data security and ownership. Users can enjoy advanced functionalities, leading to an enhanced Web3 experience.

Development Prerequisites

Before we roll up our sleeves and start building our chat application, ensure you've completed the following prerequisites:

• Follow the instructions here to configure your NEAR BOS development environment. This will get your localhost:3000 up and running.
• Head over to testnet.mynearwallet.com to create an account since we're working in a testing environment.
• Download and Install the BOS Component Loader (bos-loader) 

Create the Project Structure

Now, let's set up the project structure:

1. Create a parent folder named "tutorial".

mkdir tutorial

‍

2. Inside the "tutorial" folder, create another folder called "src."

cd tutorial 
mkdir src

3. Within the "src" folder, create a component file, e.g., Main.jsx.

cd src 
touch Main.jsx

Verify Your Component

Now, let's make sure your component is working as expected on BOS:

1. Open the Main.jsx file and add a simple "Hello" code to the Main.jsx component:

return 
Hello!

2. Run the BOS Loader command:

bos-loader  --path src

For example:

bos-loader fakela.testnet --path src

4. Open http://localhost:3000/flags and set the BOS loader URL to http://127.0.0.1:3030. 

5. Open http://localhost:3000/<youraccount.near>/widget/<componentname> (case-sensitive) to access your component.

For example:

http://localhost:3000/fakela.testnet/widget/Main

Alternatively, you can set the loader URL in https://test.near.org/flags and open https://test.near.org/<youraccount.testnet>/widget/<component name> to view your component locally.

Create the Chat Application

Now that your component is rendering correctly, let's begin building the chat application.

In your code editor, let's start by defining the contract ID:

Note: The contractId is the account where the chat smart contract is deployed and that this contract can be found in the Calimero GitHub public repository.

const contract = "chat-simple.ws-protocol-63";

Add the following CSS styling for the Chat interface. These styled components define the visual appearance of the chat application, such as message boxes, buttons, text, etc.

const Separator = styled.div`
  height: 1px;
  padding: 1px;
  width: 3rem;
  background-color: #111;
`;

const Message = styled.div`
  margin-bottom: 1rem;
  background-color: #5c5470;
  width: 100%;
  padding: 2px;
`;

const MessageData = styled.div`
  display: flex;
  column-gap: 1rem;
  margin-top: 0.5rem;
  margin-bottom: 0.5rem;
`;

const MainContainer = styled.div`
  background-color: #352f44;
  padding: 1rem;
  width: 100%;
`;

const SenderText = styled.div`
  color: #faf0e6;
  font-size: 1rem;
  line-height: 1.25rem;
  font-weight: 700;
`;
const TimeAgo = styled.div`
  color: #b9b4c7;
  font-size: 0.75rem;
  line-height: 1rem;
  margin-top: 2px;
`;

const MessageText = styled.div`
  color: #fff;
  margin-top: 1rem;
  margin-bottom: 1rem;
`;

const Title = styled.div`
  color: #fff;
  font-size: 1.25rem;
  line-height: 1.5rem;
  font-weight: 700;
`;

const IconSend = styled.i`
  margin-top: 0.3rem;
  margin-left: 1rem;
  font-size: 1.25rem;
  cursor: pointer;
  color: #797978;
  :hover {
    color: #fff;
  }
`;

const LoginText = styled.div`
  color: #fff;
`;

const ButtonJoin = styled.div`
  width: 100px;
  padding: 4px;
  background-color: #b9b4c7;
  color: #111;
  font-size: 1.25rem;
  line-height: 1.5rem;
  font-weight: 700;
  border-radius: 8px;
`;

Now, let's define state variables for your chat application. These variables set default values for various properties that the application will use to manage its data and behaviour.

State.init({
  bootstraping: true,
  loggedIn: false,
  channelList: [],
  selectedChannel: 0,
  usersList: [],
  chatMessages: [],
  message: "",
  inputId: 0,
});

Next, create functions to fetch data from the contract. These functions will retrieve information such as member lists, chat messages, and channel lists.  In the code below

•  updateMemberList fetches a list of members, and
•  updateChannelList fetches a list of chat channels/groups. 

They both use asynchronous calls to update the application's state with the fetched data.

// DATA FETCHING FUNCTIONS - VIEW CALLS
const updateMemberList = () =>
  Near.asyncCalimeroView(contract, "get_members").then((m) => {
    State.update({ usersList: m });
    return m;
  });

const updateChannelList = () =>
  Near.asyncCalimeroView(
    contract,
    "get_groups",
    { account: context.accountId },
    undefined,
    true
  ).then((c) => State.update({ channelList: c }));

state.channelList[0] &&
  State.update({
    chatMessages: Near.calimeroView(
      contract,
      "get_messages",
      {
        group: state.channelList[0],
      },
      undefined,
      true
    ),
  });

Next, we will create helper functions that will handle actions such as sending messages, joining the chat, and verifying function access keys. In the code below

•  onChangeMessage update the application's state with the content of a user's message as they type it and
• sendMessage is responsible for sending a message. 

// HELPER FUNCTIONS - CHANGE DATA OR CHANGE FUNCTIONS
const onChangeMessage = ({ target }) => {
  State.update({ message: target.value });
};

const updateInputId = (id) => {
  State.update({ inputId: id });
};
const sendMessage = () => {
  if (!state.message) {
    return;
  }
  let params = {};
  params = { group: state.channelList[0] };
  params.message = state.message;
  params.timestamp = Date.now();
  State.update({ message: "" });
  updateInputId(Math.random().toString(36));
  Near.fakCalimeroCall(contract, "send_message", params);
};

We will also define access key functions to join the chat, check membership status, and verify function access keys. In the code below the 

• joinCurb is called when a user wants to join a chat group. 
•  isMember is used to check if a user is a member of a chat group, based on their account ID and the list of members. The code checks if the application is in a "bootstrapping" state. If so, it calls the verifyKey function.
• verifyKey verifies the user's authentication key. 

After verification, the updateMemberList and updateChannelList functions are called to fetch member and channel data.

// CALIMERO FUNCTION ACCESSKEYS FUNCTIONS
const joinCurb = () => {
  Near.requestCalimeroFak(contract);
};

const isMember = (accountId, members) => {
  return (members || state.usersList)
    .map((user) => user.id)
    .includes(accountId);
};

const verifyKey = () => {
  Near.hasValidCalimeroFak(contract).then((result) => {
    State.update({ bootstraping: false, loggedIn: result });
    if (result) {
      updateMemberList().then((members) => {
        if (!isMember(context.accountId, members)) {
          Near.fakCalimeroCall(contract, "join");
        }
      });
      updateChannelList();
    }
  });
};

if (state.bootstraping) {
  verifyKey();
}

updateMemberList();
updateChannelList();

Finally, we will add a function to format the timestamp of chat messages for a user-friendly display. 

const formatTimeAgo = (seconds) => {
  const minutes = Math.floor(seconds / 60);
  const hours = Math.floor(minutes / 60);
  const days = Math.floor(hours / 24);
  const weeks = Math.floor(days / 7);
  const months = Math.floor(weeks / 4);

  if (months > 0) {
    return `${months} month${months > 1 ? "s" : ""} ago`;
  } else if (weeks > 0) {
    return `${weeks} week${weeks > 1 ? "s" : ""} ago`;
  } else if (days > 0) {
    return `${days} day${days > 1 ? "s" : ""} ago`;
  } else if (hours > 0) {
    return `${hours} hour${hours > 1 ? "s" : ""} ago`;
  } else if (minutes > 0) {
    return `${minutes} minute${minutes > 1 ? "s" : ""} ago`;
  } else {
    return `just now`;
  }
};

Rendering the Front-End

Now, let's build the user interface for the chat application. This code below will render the chat interface, messages, input field, membership status, etc

return (
  
    {context.accountId ? (
      <>
        {state.bootstraping ? (
          
        ) : (
          <>
            {state.loggedIn && isMember(context.accountId) ? (
              

                
                {!state.chatMessages ||
                  (state.chatMessages.length === 0 && (
                    
                  ))}
                

                  {(state.chatMessages || []).map((message, id) => (
                    
                      
                        
                        {message.sender}
                        
                          {formatTimeAgo(
                            (Date.now() - message.timestamp) / 1000
                          )}
                        
                      

                      {message.text}
                    
                  ))}
                
                

                   {
                      if (e.key == "Enter") {
                        sendMessage();
                      }
                    }}
                    placeholder={"send a message"}
                    key={state.inputId}
                    value={state.message}
                    autoFocus
                  />
                   sendMessage()}
                  >
                
              
            ) : (
              Join Chat
            )}
          
        )}
      
    ) : (
      
    )}
  
);

Testing Your Chat Application

Now that you've built the chat application using BOS and Calimero, go back to http://localhost:3000/<youraccount.near>/widget/<componentname> to load and test your application.

For the full source code, check out the Calimero GitHub repository.

We hope you find this guide helpful in building a decentralized chat application using Calimero and BOS.  If you have any questions or need further assistance, please don't hesitate to contact our support team. Happy coding!