Establishing a connection to Chromia

This lesson walks you through connecting a client to the Chromia blockchain. You will build an example client step by step, beginning with the imports at the top of a new file, book_review.ts.

import { encryption, createClient, newSignatureProvider, IClient, MERKLE_HASH_VERSIONS } from "postchain-client";import * as readline from "readline";

Then add a main function and a helper function that reads user input:

async function main() {}

Creating a client with createClient

Calling createClient gives you a client instance for querying the blockchain and submitting transactions. Add the call as shown below. Its parameters are explained afterwards.

let client: IClient;const blockchainRID = "<Blockchain RID>";async function main() {  client = await createClient({    nodeUrlPool: "http://localhost:7740",    blockchainRid: blockchainRID,  });}

Parameters:

• nodeUrlPool: The URL of the node to connect to. During development you usually run a Chromia node locally, commonly at http://localhost:7740. On testnet or in production, you point this at a remote node's address instead.

• blockchainRid: The blockchain's Referential Identifier (RID). This hexadecimal string is unique to each Chromia blockchain and tells them apart.

The snippet above connects to a node running locally and selects the target blockchain by its RID.

Why both values matter

• Specificity: One Chromia node can host several blockchains. The RID makes sure your client talks to the right one.

• Flexibility: Because the node URL and RID are parameters, you can move between environments such as development, staging and production, or target a different blockchain, without touching your application's core logic.

Finding the blockchain RID: With a node running, run the following command to ask it for the RID:

curl http://localhost:7740/brid/iid_0

Signing a transaction with postchain-client

The postchain-client library makes signing Chromia transactions straightforward. The steps below cover the full process.

Generate a keypair

Signing requires a cryptographic keypair: a private key and its matching public key. Add the code below to book_review.ts, supplying the private key of the admin bookkeeper configured in chromia.yml:

const privKey = Buffer.from("<private key>", "hex");const bookKeeperKeyPair = encryption.makeKeyPair(privKey);

makeKeyPair, part of the encryption module, builds a keypair from the private key you pass in (privKey). The returned bookKeeperKeyPair holds the private key, which signs, and the corresponding public key, which verifies.

If you followed the earlier instructions and used the book_admin key id, read the private key from the .chromia folder as follows:

cat ~/.chromia/book_admin

Secure storage and retrieval of keys

Cryptographic keys must be stored securely so that no one else can access them. The Chromia key generation documentation describes recommended practices for creating, storing and managing keys, including where to place key files and other security measures.

Set up the signature provider

With the keypair ready, you need something that applies it to transactions. Add a SignatureProvider to book_review.ts:

const bookKeeperSignatureProvider = newSignatureProvider(MERKLE_HASH_VERSIONS.TWO, bookKeeperKeyPair);

newSignatureProvider takes your keypair (bookKeeperKeyPair) and returns a signature provider. Every transaction is signed by this provider before it goes to the blockchain.

Sending a transaction with signAndSendUniqueTransaction

You can now add the first transaction inside the main function of book_review.ts:

  console.log("Creating a new book transaction");  await client.signAndSendUniqueTransaction(    { name: "create_book", args: ["ISBN1", "Chromia 101", "John Doe"] },    bookKeeperSignatureProvider  );

In the postchain-client library, signAndSendUniqueTransaction handles two jobs in one call:

• Signing: The transaction is signed with the given signature provider before it leaves the client. When the network verifies the signature, it confirms who sent the transaction and that nothing changed after signing.

• Sending: The signed transaction is then submitted to the Chromia blockchain for processing.

Parameters explained:

The method accepts two arguments:

1. Transaction object:

   • name: The operation to run on the blockchain. Here, "create_book" maps to a Rell operation that creates a new book entity on the blockchain.
   • args: An array holding the arguments the operation needs.

2. Signature provider: Signs the transaction with the keypair created earlier. The snippet passes bookKeeperSignatureProvider.

How it fits into the overall flow:

A call to signAndSendUniqueTransaction tells the client to:

• Build a transaction that calls create_book on the blockchain with the given arguments.
• Sign it with bookKeeperSignatureProvider.
• Submit the signed transaction to the Chromia blockchain.

Testing your code

At the bottom of the file, add a call that runs main:

main();

Run the example:

npx tscnode book_review.js

The next step adds a query that fetches books and reviews.