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
- Install
Node.js
(Node 18 in particular if running in a Node environment); see Node.js Installation Guide. - Install TypeScript; see TypeScript Installation Guide.
- Have a Rell backend up and running; see Build and run the Hello World dapp with Chromia CLI.
- Initialize a TypeScript project; see TypeScript Project Setup.
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.
- Install the
postchain-client
fromnpm
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.
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.
- 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.
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.
- 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.
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.
- 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.
- 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
- Replace
<TargetUrl>
forchromiaD1URL
and<BlockchainRID>
forchromiaD1blockchainRID
with the URL and the Blockchain RID of a Chromia node running the D1 chain. Also, replace<BlockchainRID>
fordappBlockchainRID
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.