Skip to main content

Interact with your dapp using the Chromia JavaScript client

This topic covers how to send transactions to and retrieve information from a blockchain node running Rell with the help of a postchain client library. The postchain-client allows a user to connect a frontend to a running backend of a dapp. 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.

Prerequisite​

Client setup​

Once your Rell backend is up and running on a blockchain node and the TypeScript project is ready, you can install the postchain-client.

  1. Install the postchain-client from npm in your project directory.
npm install postchain-client --save

The client code in this tutorial provides a key pair (public and private). The key pair only works when you run a dapp locally. Otherwise, the key pair should be unique for you as a user and stored somewhere secure. Moreover, the client code file includes information about the REST Client connection and the GTX client connection. The connection setup is followed by a transaction, which is created, signed, and posted to the blockchain node. Lastly, a query is called to retrieve the added information in the transaction. The client code setup is more thoroughly explained in the Clients - JavaScript section.

info

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

  1. Add the client code, shown below, to the index.ts file. Replace the <BlockchainRID> with your Blockchain RID from the node output. Information about finding Blockchain RID is available at 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 nodeApiUrl = "http://localhost:7740/"; //Using default postchain node REST API port
  const blockchainRID = "<BlockchainRID>"; //Dapp Blockchain RID
  const rest = pcl.restClient.createRestClient([nodeApiUrl], blockchainRID); //REST Client connection
  const gtx = pcl.gtxClient.createClient(rest, blockchainRID, ["set_name"]); //gtx Client connection

  //Transaction
  const request = gtx.newTransaction([adminPubkey]); //Create transaction
  request.set_name("Developer"); //Call operation
  request.addOperation("nop", randomInt(12345678)); //A random int to make the hash of the transaction unique

  request.sign(adminPrivkey, adminPubkey); //Sign transaction
  await request.postAndWaitConfirmation(); //Post to blockchain node

  //Query
  const result = await gtx.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.

  1. Execute the following commands to run the client code file. Make sure to be in the src/ folder working directory.
tsc index.ts
node index.js

You'll see the following message in the terminal.

"Hello Developer!"

Awesome. With the help of the postchain client library, you have now sent transactions and retrieved information from a blockchain node running Rell.

Configure client for Chromia network​

You can also use the postchain-client with a dapp backend running on the Chromia network by setting up a connection to a Directory 1 (D1) node. Every blockchain connects to the D1 node, a service chain. Through the D1 connection, the client finds all the addresses where your dapp is currently running and establishes a connection encountering the list of addresses.

info

If you're configuring your client for the public Chromia Testnet, use the following Directory 1 node URL as the chromiaD1Url and chromiaD1blockchainRID variable below:

const chromiaD1Url = "https://node0-delta.chromia.dev:7740";

const chromiaD1blockchainRID = "E657470405E234386DBF287FC4658580613A8FAF62DCE0EAE503C4A794CCFEC4";

For the current Testnet of Chromia, there is only one node using HTTPS (https://node0-delta.chromia.dev:7740). Therefore, if you are hosting your frontend using HTTPS, you must configure your client to only connect to that single node. Skip the following section and use the previous example, substituting the URL of the node mentioned above.

To make this possible, you need a dapp. For more information, see Deploy your dapp to Testnet.

  1. Remove the local key pair in the client code (configured for a local setup). Instead, link to your key pair stored somewhere secure. For more information, see Deploy your dapp to Testnet.
//Key pair
const adminPubkey = Buffer.from("<PubkeyLink>", "hex");
const adminPrivkey = Buffer.from("<PrivkeyLink>", "hex");

To connect to the Chromia network, you need to specify a URL and a Blockchain RID of a Chromia node running the D1 chain (service chain) in the client code file.

The REST Client is then configured for the specific Chromia base URL and Blockchain RID. This is followed by an instance of a Chromia Client provider. It uses the REST Client instance and allows calls to the D1 chain.

Thereafter, you can set a connection with a blockchain of the dapp Blockchain RID. It returns a REST Client with the addresses of the nodes that run your blockchain.

  1. In the client code file (configured for a local setup) replace the following part
const nodeApiUrl = "http://localhost:7740/"; //Using default postchain node REST API port
const blockchainRID = "<BlockchainRID>"; //Dapp Blockchain RID
const rest = pcl.restClient.createRestClient([nodeApiUrl], blockchainRID); //REST Client connection

with this part.

//Connection input
const chromiaD1blockchainRID = "<BlockchainRID>"; //Target Blockchain RID
const chromiaD1Url = "<TargetUrl>"; //Target URL

//Connection setup
const restD1 = pcl.restClient.createRestClient(
  [chromiaD1Url],
  chromiaD1blockchainRID,
  5,
  1000
); //REST Client connection
const chromiaClient = pcl.chromiaClient.chromiaClientProvider(
  chromiaD1blockchainRID,
  restD1
); //Chromia Client provider
const dappBlockchainRID = "<BlockchainRID>"; //Dapp Blockchain RID
const rest = await chromiaClient.blockchainConnection(dappBlockchainRID); //Blockchain connection
  1. Replace <TargetUrl> for chromiaD1URL and <BlockchainRID> for chromiaD1blockchainRID with the URL and the Blockchain RID of a Chromia node running the D1 chain. Also, replace <BlockchainRID> for dappBlockchainRID with your dapp Blockchain RID.

With these steps, you are ready to use the postchain-client with a dapp backend running on the Chromia network.