Setting up the front-end#

In this part, you will create a web front-end. Users can interact with the smart contract easier by using your front-end compared to interacting with the node directly. Non-tech users might find it inconvenient to interact with smart contracts via the Concordium node and some users may choose not to host their own Concordium node locally. This tutorial part will show you a setup that alleviates the need for the user to host their own Concordium node.

You can lower the bar for entry by coding an appealing front-end that provides additional information to your potential customers. Web front-ends are a familiar sight nowadays, but to use the front-end, users will also need to download a browser wallet as a browser extension. The installation and safe usage of the browser wallet might be new for people using your front-end. Providing comprehensive explanations and step-by-step guides on your website on topics related to the browser wallet is important for a good user experience. The browser wallet connects via HTTPS to a server that is connected to a Concordium node. This setup alleviates the need for the user to host their own Concordium node.

Note

Before you start with part 3 of this tutorial, make sure you have:

access to the Chrome web browser on your computer
git installed to be able to clone a repository from GitHub
node.js and yarn installed

Node.js is a JavaScript runtime environment and yarn is a package manager used in combination with node.js. You can download node.js and yarn on their official websites.

Concordium browser wallet#

A browser wallet is a piece of code that can be added as an extension to supported browsers such as Chrome. The browser wallet allows you to interact with the chain and make transactions. Currently, the browser wallet does this by connecting to a (JSON-RPC) server that communicates with a node. The browser wallet hosts the private keys corresponding to the accounts of the user and a link that points to a server.

Your front-end code that is run in the browser constructs the transaction object and sends it to the browser wallet. The transaction object is signed by the private key hosted in the browser wallet and transmitted to the server via HTTPS. This server has access to a Concordium node and converts the request (including the signed transaction object) that comes via HTTPS from the browser wallet to a request that the Concordium node can execute. The signed transaction is transmitted via peer-to-peer communication to other Concordium nodes and becomes part of the Concordium blockchain.

Warning

The Concordium browser wallet is in active development. A pre-MVP (minimum viable product) version is currently available to be built from the source code. Expect some breaking changes until the MVP version is released in the next quarter. It is not recommended to use any pre-MVP product on mainnet.

You can choose from two different workflows that will guide you through the setup steps. Workflow 1 is easier. The server that the browser wallet connects to is hosted by Concordium in workflow 1. This setup will take care of the Concordium node on your behalf. Workflow 2 is for advanced readers that want to build all the components from the source code and connect the browser wallet to their own hosted Concordium node.

Workflow 2 - Setup browser wallet connected to local node (click here)

Before you start this workflow, make sure you have:

a running Concordium testnet node that fully caught up.
have port forwarding enabled (This step is only required when you run your node on a remote server instead of locally. See the note below):

Note

When your node is running on a remote server your cloud provider usually gives you an option to ssh into it. Add the following port forwarding rule to your method to ssh into your instance by running the command in another terminal. The port 10001 on your localhost is forwarded to the port 10001 on your instance.

$ssh -NL localhost:10001:<IP-address-of-your-instance>:10001 <username>@<host>

If you don’t have a running testnet node or port forwarding enabled, the piggy bank tutorial part 3 will guide you through these setup steps.

These prerequisites ensure that you have a testnet node reachable locally on port 10001. The browser wallet requires the Concordium JSON-RPC server that points to your node. Clone the repository with the command:

$git clone https://github.com/Concordium/concordium-json-rpc.git

Build and run the server as described in the README file of the JSON-RPC repository.

The final command that you execute to start the JSON-RPC server is as follows:

$yarn start --port 9095 --nodeAddress 127.0.0.1 --nodePort 10001 --nodeTimeout 5000

Your JSON-RPC server is running on port 9095 and connects to your local node on port 10001. You are ready now to build the pre-MVP browser wallet from the source code. Clone the repository with the command:

$git clone https://github.com/Concordium/concordium-browser-wallet.git

You can build the browser wallet extension and load the dist folder (located at root/packages/browser-wallet/dist) into the Chrome browser as described in the README file of the browser wallet repository.

Note

Depending on the exact commit hash that you used to build your pre-MVP browser wallet, the screenshots and setup steps might differ.

The next steps are based on the pre-MVP browser wallet from a git commit before 22.8.2022. These early versions of the pre-MVP browser wallet have an input field for the private key to import an already existing account and an input field for the link to the JSON-RPC server. Alternatively, you can follow workflow 1 to use the most recent pre-MVP browser wallet without hosting your own node and JSON-RPC server. The newer browser wallet from workflow 1 can be used to create a new account (no importing of private keys needed).

You are ready now to start the browser wallet by clicking on the Concordium icon at the top right of the Chrome browser.

Note

The puzzle icon at the top right of the Chrome browser allows you to manage your browser extensions. You can enable pinning of the Concordium browser wallet.

You have to enter your private key into the browser wallet. You might have already an account in the concordium-client or in the Concordium mobile wallet. You can decrypt the private keys of these accounts and use them in the browser wallet. Download the utils tool under the auxiliary tools section. This tool is able to decode your encrypted key. You can find additional information on the utils tool and how to decrypt your keys here.

You have to enter the private key and the associated account into the browser wallet similar to the below string.

74ff83a13ca066298583dcb9151822359fd2e4c9b69c9ca427455da565f6129b,3oLNhuxM7yrf3LrJa3hH5NfocTViGS8Aj2t6YScWNvUq4o2nC

Enter the below JSON-RPC endpoint into the browser wallet to connect to your local JSON-RPC server on port 9095.

http://127.0.0.1:9095

You completed the browser wallet setup. Check that your account balance is displayed and you have enough CCD to be able to execute transactions.

Note

You are connected to a website with your browser wallet when you see the green Connected button. You can toggle on/off the connection by clicking on the button.

Running the web front-end#

You have successfully added the Concordium browser wallet extension to your browser in the previous section. In the next step of the tutorial, you are going to clone a wCCD demo front-end written with the React library and run it locally. The demo front-end has the required packages installed to connect to the Concordium browser wallet and implements common flows to deal with the different states that the browser wallet could be in. For example, the front-end will display a connect wallet button when loading the website. Furthermore, the front-end has flows to react to the events when the user switches the account in the browser wallet or connects/disconnects an account in the browser wallet to update the front-end state accordingly.

Note

React is a popular open-source front-end JavaScript library.

Clone this repository.

$git clone https://github.com/Concordium/concordium-browser-wallet.git

Build and run the front-end as described in the README file of the wCCD front-end demo.

The steps in the README file are as follows:

Run yarn in the root folder to install all dependencies.

$yarn

Run yarn build:all to build the concordium-helpers package.

$yarn build:all

Navigate to the wCCD example folder.

$cd ./examples/wCCD/

Run yarn watch to enable hot-reload (useful for development) of the web front-end whenever you do any changes to the code.

$yarn watch

Run yarn start in another terminal to start the web front-end.

$yarn start

This command logs a URL in the console (typically http://127.0.0.1:8080). Open this URL in the Chrome browser.

Note

Check that your browser wallet is connected to the testnet (screenshots shown in workflow 1) or a testnet node (workflow 2) and not to mainnet or stagenet.

You completed the local front-end setup.

To continue with the tutorial click here.

Interacting with the wCCD token protocol

Running your first full dApp