Interact with your dapp

This guide explains how to send transactions to a blockchain node running Rell and retrieve information from it using the postchain-client library. The postchain-client allows you to connect the frontend of your dapp to the backend. This client tutorial is a continuation of the Rell backend generated from the section Build and run the Hello World dapp with Chromia CLI and guides you through how to set up your client side. You can connect the frontend at a later stage.

Prerequisites

• Install Node.js (Node 18 in particular if running in a Node environment); see Node.js Installation Guide.
• If utilizing types, install TypeScript; see TypeScript Installation Guide.
• Ensure your Rell backend is up and running; see Build and run the Hello World dapp with Chromia CLI.
• Initialize a JavaScript or TypeScript project; see TypeScript Project Setup.

Client setup

After setting up your Rell backend on a blockchain node and initializing your client project, you can install the postchain-client library.

1. Install postchain-client using npm in your project directory.

npm install postchain-client --save

The client code provided in this guide includes a key pair (public and private) that is valid for running a dapp locally. If running in a different environment, make sure to use a unique and secure key pair. The code also establishes the client connections, creates, signs, and posts a transaction to the blockchain node, and retrieves information through a query. For detailed explanation of the code setup, see Clients - JavaScript.

info

If you want to configure the client code to connect to a dapp backend running on the Chromia network, see Configure Client for Chromia Network.

warning

Using modules like crypto and Buffer, you may encounter errors depending on the bundler you're using. For instance, webpack 5 does not automatically polyfill these packages as webpack 4 and earlier versions do. Consequently, manual configuration is required to polyfill and use these modules in order to avoid such errors.

2. Add the client code to your index.ts file, replacing <BlockchainRID> with your Blockchain RID obtained from the node output. For information on finding Blockchain RID, see Build and run the Hello World dapp with Chromia CLI.

import { randomInt } from "crypto";
import * as pcl from "postchain-client";

async function simpleClient() {
  //Key pair
  const adminPubkey = Buffer.from(
    "031b84c5567b126440995d3ed5aaba0565d71e1834604819ff9c17f5e9d5dd078f",
    "hex"
  );
  const adminPrivkey = Buffer.from(
    "0101010101010101010101010101010101010101010101010101010101010101",
    "hex"
  );

  //Connection setup
  const nodeUrl = "http://localhost:7740/"; //Using default postchain node REST API port
  const blockchainRid = "<BlockchainRID>"; //Dapp Blockchain RID
  const chromiaClient = await pcl.createClient({
    nodeUrlPool: nodeUrl,
    blockchainRid: blockchainRid,
  });

  //Transaction
  const { status, statusCode, transactionRid } =
    await chromiaClient.signAndSendUniqueTransaction(
      {
        operations: [
          {
            name: "set_name",
            args: ["Developer"],
          },
        ],
        signers: [adminPubkey],
      },
      { privKey: adminPrivkey, pubKey: adminPubkey }
    );

  //Query
  const result = await chromiaClient.query("hello_world");

  console.log(result);
}

simpleClient();

The added client code works with the operation and query specified in the Rell file main.rell, provided in the topic Build and run the Hello World dapp with Chromia CLI. The code in the main.rell file is as follows.

module;

object my_name {
  mutable name= "World";
 }

operation set_name(name) {
  my_name.name = name;
}

query hello_world() = "Hello %s!".format(my_name.name);

The project structure for the client setup should be as follows.

My_Rell_Project
    |--_node_modules
    |--_src
        |--index.ts
    |--package-lock.json
    |--package.json
    |--tsconfig.json

Run client code

The last step is to run the client code file.

note

How to run the client code file in this tutorial is just an example of a default TypeScript project setup with the project structure, as discussed in the previous section.

3. Execute the following commands to run the client code file. Make sure to be in the src/ folder working directory.

npx tsc index.ts
node index.js

After running the code, you should see the following message in the terminal:

"Hello Developer!"

Congratulations! With the help of the postchain-client library, you have successfully sent transactions and retrieved information from a blockchain node running Rell.