# JavaScript/TypeScript client details · Chromia Docs (concept)

> We are currently updating this documentation. While it offers a general overview, some details may be outdated. Please

Source: https://docs.chromia.com/build/clients/postchain-clients/javascript-typescript/reference/

# JavaScript/TypeScript client details

On this page

* [Installation](#installation)
* [Initializing the client](#initializing-the-client)
* [Parameters](#parameters)
* [Returns](#returns)
* [Use sticky node](#use-sticky-node)
* [Failover strategies](#failover-strategies)
* [Queries](#queries)
* [Query option 1](#query-option-1)
* [Query option 2](#query-option-2)
* [Typed query 1](#typed-query-1)
* [Typed query 2](#typed-query-2)
* [Transactions](#transactions)
* [Simple transaction](#simple-transaction)
* [Signing a transaction](#signing-a-transaction)
* [Sending an unsigned transaction](#sending-an-unsigned-transaction)
* [Sending a signed transaction](#sending-a-signed-transaction)
* [Sending a signed transaction (with status polling enabled)](#sending-a-signed-transaction-with-status-polling-enabled)
* [Advanced transaction](#advanced-transaction)
* [PromiEvent](#promievent)
* [External signing example](#external-signing-example)
* [ICCF](#iccf)
* [Architecture](#architecture)
* [Contributing to the project](#contributing-to-the-project)
* [Run tests](#run-tests)

note

We are currently updating this documentation. While it offers a general overview, some details may be outdated. Please
check back soon for the latest version.

JavaScript/TypeScript client contains a set of predefined functions and utilities offering a convenient and simplified
interface for interacting with a decentralized application (dapp) built using the Postchain blockchain framework, also
known as Chromia.

tip

You can find detailed examples of the JavaScript client in the
[React/Rell course](https://chromia.com/learn/my-news-feed/module-two/connecting-the-client/).

## Installation

The Postchain client is compatible with both JavaScript and TypeScript. The library is distributed on npm (Node Package
Manager) and can be easily installed in your project. You have two options to install it:

1. Visit the npm package page for postchain-client and follow the installation instructions provided there, see
   [npm-postchain-client](https://www.npmjs.com/package/postchain-client).
2. In your project's terminal or command prompt, execute the following command: `npm install postchain-client`. This
   command will download and install the library in your project.

## Initializing the client

Firstly, import the required libraries.

TypeScript

```
import crypto from "crypto-browserify";
import secp256k1 from "secp256k1";
import { encryption, createClient, newSignatureProvider } from "postchain-client";
```

Then, create some dummy keys.

TypeScript

```
const signerPrivKeyA = Buffer.alloc(32, "a");
const signerPubKeyA = secp256k1.publicKeyCreate(signerPrivKeyA);
const signerPrivKeyB = Buffer.alloc(32, "b");
const signerPubKeyB = secp256k1.publicKeyCreate(signerPrivKeyB);
```

Each blockchain has a Blockchain RID (`blockchainRID`) that identifies the specific blockchain we wish to interact with.
This blockchainRID should match the Blockchain RID encoded into the first block of the blockchain. How the blockchainRID
is structured depending on the creator of the blockchain. In this example, we use the Linux command: echo
`"A blockchain example"| sha256sum`.

`const blockchainRid = "7d565d92fd15bd1cdac2dc276cbcbc5581349d05a9e94ba919e1155ef4daf8f9";`

Create a Chromia client instance and configure it according to your needs.

### Parameters

* `settings` (Object): A set of network settings to customize the behaviour of the Chromia client.
  + `nodeUrlPool` (Optional): An array of URLs representing the nodes the client will send requests to. Use this if you
    know the specific nodes handling the client requests. These nodes can be local or belong to the same cluster as the
    targeted blockchain.
  + `directoryNodeUrlPool` (Optional): An array of URLs representing nodes in the system cluster, where the directory
    chain is located. The client will automatically discover every node running the targeted application by querying the
    Directory Chain. This can be useful when the client needs to automatically adapt to updates to the nodes within the
    cluster where the blockchain is located."
  + `blockchainRid` (Optional): Resource Identifier (Rid) of the targeted blockchain. This is a unique identifier for
    the specific blockchain.
  + `blockchainIid` (Optional): Instance Identifier (Iid) of the targeted blockchain. The Directory Chain always has
    Iid 0.
  + `statusPollInterval` (Optional): Interval (in milliseconds) at which the client will poll the status after posting a
    transaction.
  + `statusPollCount` (Optional): Number of consecutive successful status polls before it should stop asking for the
    status. Defaults to 1.
  + `failOverConfig` (Optional): Configuration for failover behaviour in case of node failures.
    - `strategy` (Optional): Failover strategy to use. Defaults to a strategy called Abort On Error.
    - `attemptsPerEndpoint` (Optional): Number of consecutive failed attempts allowed for each endpoint before
      considering it unreachable. Defaults to 3.
    - `attemptInterval` (Optional): Interval (in milliseconds) between consecutive retry attempts during failover.
      Defaults to 5000 ms.
    - `unreachableDuration` (Optional): Duration (in milliseconds) that an endpoint should remain unreachable before
      reattempting. Defaults to 30000 ms.
  + `useStickyNode`(Optional): A boolean that will ensure that on succefull requests to a node, the client will continue
    using this node unless it starts failing.

### Returns

A promise that resolves to the configured Chromia client instance.

Example:

1. Client configured with a known node URL:

TypeScript

```
const chromiaClient = await createClient({
  nodeUrlPool: "http://localhost:7740",
  blockchainRid,
});
```

2. The client is configured for node discovery with an array of URLs representing nodes in the system cluster.

TypeScript

```
const chromiaClient = await createClient({
  directoryNodeUrlPool: ["url1", "url2", "url3", "etc."],
  blockchainRid,
});
```

### Use sticky node

**What is a "sticky node"?**

A sticky node is a node that will continue to be used for requests as long as the requests to it are successful, this
means that if the client is requesting to get the block height of a dapp, and it is successful, then following requests
to get other data e.g.: dapp transactions will be using the same node, meaning that is "sticks" with the user once
selected.

**How does it work?**

The client will need to be initialized with a `directoryNodeUrlPool` and have the property `useStickyNode` set to `true`
in the `settings` parameter for it to be enabled. Example:

TypeScript

```
const client = createClient({
  useStickyNode: true,
  directoryNodeUrlPool: ["http://localhost:7740"],
  ...restSettings,
});
```

This will then create internally create a nodeManager that handles and keeps track of which nodes are available and
which one is currently set to be the "sticky node".

As a user, when you first request with this feature enabled, you will not have any "sticky node" set. Instead, whenever
you request, the client will choose a random node out of the ones available. Should the request to the node be
successful, then that node will be set as the "sticky node". This will happen regardless of what failoverStrategy has
been set.

Any subsequent requests after the first successful one will continue to use the "sticky node" if it continues to give
successful requests. Should the node fail, however, then it will be set at unavailable for the duration configured in
the client settings (or the default time of 30000ms), and following requests will once again try to use a random
available node and, if successfully set that one as the new "sticky node".

**Setting how long a node should be unavailable**

The duration that a node is configured as unavailable can be se in the failoverConfig of the client settings:

TypeScript

```
const client = createClient({
useStickyNode: true,
directoryNodeUrlPool: ["http://localhost:7740"],
failOverConfig: {
startegy: "abortOnErrror",
attemptsPerEndpoint: 4,
attemptInterval: 3000,
unreachableDuration: 50000,
}
...restSettings
})
```

### Failover strategies

When initializing a client, you can configure the failover strategy for the client. Additionally, you can modify
specific parameters within the failover configuration, such as the number of attempts per endpoint and the interval
between attempts.

The Postchain client offers three failover strategies:

**Abort on error**

The request strategy will abort on client error and retry on server error. The request strategy will not retry the query
if a client error occurs, such as an invalid query parameter. However, the request strategy will retry the query on
another node if a server error occurs, such as a timeout or internal server error.

**Try next on error**

The Try Next On Error request strategy is similar to Abort On Error but will also retry on client error. This means that
if a client error occurs, the request strategy will retry the query on another node, as well as retry on the server
error.

**Single endpoint**

The single endpoint request strategy will not retry on another node.

**Query majority**

The query majority request strategy will query all nodes in parallel and wait until an EBFT majority of the nodes return
the same response. This can ensure the system's integrity by requiring a consensus among nodes before accepting a
result.

## Queries

### Query option 1

Use the query function to send a query to a dapp written in Rell. The function takes the query's name and an object of
query arguments.

TypeScript

```
chromiaClient.query("get_foobar", {
  foo: 1,
  bar: 2,
});
```

### Query option 2

Alternatively, the query function can take an object with a `name` property and an `args` property.

TypeScript

```
chromiaClient.query({
  name: "get_foobar",
  args: {
    foo: 1,
    bar: 2,
  },
});
```

### Typed query 1

You can specify argument and return types for a given query in TypeScript.

TypeScript

```
type ArgumentsType = {
  foo: number;
  bar: number;
};

type ReturnType = {
  foobar: string;
};

const result = await chromiaClient.query<ReturnType, ArgumentsType>("get_foobar", {
  foo: 1,
  bar: 2,
});
```

### Typed query 2

Alternatively, you can specify the types in a `QueryObject` to achieve type safety

TypeScript

```
type ReturnType = {
  foobar: string;
};

const myQuery: QueryObject<ReturnType> = {
  name: "get_fobar",
  args: { foo: "bar" },
};
const result = await chromiaClient.query(myQuery); // result has type ReturnType
```

## Transactions

To send transactions, begin by creating a simple signature provider. The signature provider is used to sign
transactions. More details on usage are provided further below.

TypeScript

```
const signatureProviderA = newSignatureProvider({ privKey: signerPrivKeyA });
```

### Simple transaction

The `signAndSendUniqueTransaction` function streamlines the transaction-sending process in three steps. It adds a "nop"
(no operation) with a random number that ensures the transaction is unique, signs it with a signature provider or
private key, and sends it. The function generates a receipt with a status code, status, and tansactionRid. The status
code indicates whether the server successfully processed the transaction. The status represents the current stage of the
transaction on the blockchain, which can be one of the following: `Waiting`, `Rejected`, `Confirmed`, or `Unknown`.

TypeScript

```
const { status, statusCode, transactionRid } = await chromiaClient.signAndSendUniqueTransaction(
  {
    operations: [
      {
        name: "my_operation",
        args: ["arg1", "arg2"],
      },
    ],
    signers: [signatureProviderA.pubKey],
  },
  signatureProviderA
);
```

It is also possible to pass a single operation.

TypeScript

```
const { status, statusCode, transactionRID } = await chromiaClient.signAndSendUniqueTransaction(
  {
    name: "my_operation",
    args: ["arg1", "arg2"],
  },
  signatureProviderA
);
```

### Signing a transaction

Signs a transaction using the provided signing method. This can be a SignatureProvider or a key pair. A signature
provider must contain a public key and a `sign` function that returns the signature of a digest transaction.

TypeScript

```
const signedTx = await chromiaClient.signTransaction(
  {
    operations: [
      {
        name: "my_operation",
        args: ["arg1"],
      },
    ],
    signers: [signatureProviderA.pubKey],
  },
  signatureProviderA
);
```

### Sending an unsigned transaction

TypeScript

```
const receipt = await chromiaClient.sendTransaction({
  name: "my_operation",
  args: ["arg1", "arg2"],
});
```

### Sending a signed transaction

TypeScript

```
chromiaClient.sendTransaction(signedTx);
```

### Sending a signed transaction (with status polling enabled)

TypeScript

```
chromiaClient.sendTransaction(signedTx, true);
```

### Advanced transaction

Create a transaction object.

TypeScript

```
const tx = {
  operations: [
    {
      name: "my_operation_1",
      args: ["arg1", "arg2"],
    },
    {
      name: "my_operation_2",
      args: ["arg1", "arg2"],
    },
  ],
  signers: ["signer1", "signer2"],
};
```

You can modify the object to add operations or signers.

TypeScript

```
tx.operations.push({
  name: "my_operation_3",
  args: ["arg1", "arg2"],
});

tx.signers.push("signer3");
```

A nop can be added to make the transaction unique. It can be added manually to the transaction object or by using the
`addNop` function.

`const uniqueTx = chromiaClient.addNop(tx);`

Sign and send the transaction.

TypeScript

```
const signedTx = await chromiaClient.signTransaction(uniqueTx, signatureProviderA);

const receipt = await chromiaClient.sendTransaction(signedTx);
```

## PromiEvent

When using functions that involve sending a transaction, you can either wait for a promise or act on an event. The
return value, in this case, is a "PromiEvent," which combines the functionalities of both a "Promise" and an "Event."
This combination allows you to handle asynchronous operations. You can treat it as a Promise by utilizing the .then()
and .catch() methods to handle the result of any potential errors. Moreover, it emits an event when a transaction is
sent, allowing you to listen to the event and execute custom logic based on your specific needs.

TypeScript

```
chromiaClient
  .sendTransaction({
    name: "my_operation",
    args: ["arg1", "arg2"],
  })
  .on("sent", (receipt: TransactionReceipt) => {
    console.log("The transaction is sent");
  });
```

## External signing example

This example demonstrates that you can use external signing mechanisms. It could involve a complex function requiring
you to sign from your phone, another device, or a different method

TypeScript

```
function askUserBToSign(rawGtxBody) {
  const digest = getDigestToSignFromRawGtxBody(rawGtxBody);
  return Buffer.from(secp256k1.ecdsaSign(digest, signerPrivKeyB).signature);
}
```

This complex signature process can be implemented in a SignatureProvider. Once you have a callback like the one above,
creating a signature provider is straightforward:

TypeScript

```
const signatureProviderB = {
  pubKey: signerPubKeyB,
  sign: askUserBToSign,
};
```

## ICCF

Creates a proof transaction for [ICCF](https://docs.chromia.com/get-started/use-cases/cross-chain/iccf/) (Inter-Chain Communication Framework). This
function generates a proof that a specific transaction has occurred on the source blockchain. The function returns a
transaction object with an operation called `iccf_proof`, and the operation that the proof should accompany should be
added to this transaction object. The transaction can then be signed and posted to the target blockchain.

TypeScript

```
const managementBlockchainRid = "7d565d92fd15bd1cdac2dc276cbcbc5581349d05a9e94ba919e1155ef4daf8f9";

const chromiaClient = await createClient({
  nodeUrlPool: "<url-node-running-managementchain>",
  managementBlockchainRid,
});

const txToProveRid: Buffer = <txRid>;
const txToProveHash: Buffer = <txHash>;
const txToProveSigners: Pubkey[] = [<signer1>, <signer2>];
const sourceBlockchainRid: string = "<sourceBlockchainRid>";
const targetBlockchainRid: string = "<targetBlockchainRid>";

const { iccfTx, verifiedTx } = createIccfProofTx(chromiaClient, txToProveRID,txToProveHash,txToProveSigners, sourceBlockchainRid, targetBlockchainRid);
```

`iccfTx` is a transaction object with an operation called `iccf_proof` and an argument containing the composed proof. To
this transaction object, you can now add the operation needing proof. Finally, the transaction object is ready to be
signed and sent.

If necessary, it is possible to solely verify whether a specific transaction has been included in the anchoring
blockchain:

TypeScript

```
isBlockAnchored(sourceClient, anchoringClient, txRid);
```

To create an anchoring client there is an utility function:

TypeScript

```
const anchoringClient = getAnchoringClient();
```

## Architecture

In the Postchain client, Generic Transactions (GTX) simplify Postchain user implementations. Users do not need to invent
a binary format for their transactions. The client will serialize the function calls, sign them, and send them to
Postchain. Read GTX in the [docs](https://docs.chromia.com/get-started/about/protocols/).

Plain text

```
User
 |
 | chromiaClient.sendTransaction()
 |
 v
 |
 | <Buffer with serialized message>
 |
 v
 |
 | POST http://localhost:7741/tx {tx: 'hex-encoded message'}
 |
 v
RestApi
 |
 | <Buffer with serialized message>
 |
 v
Postchain
 |
 | backend.fun1(conn, tx_iid, 0, [pubKeyA], 'arg1', 'arg2');
 | backend.fun2(conn, tx_iid, 1, [pubKeyA], 'arg1');
 |
 v
Backend
```

## Contributing to the project

### Run tests

Unit tests:

`npm run test:unit`

Integration tests:

1. Make sure a Postgres database is running. Read more here.
2. Start blockchain

   `cd resources/testDapp`

   `chr node start --wipe`
3. Run tests

   `npm run test:integration`

[View this page on docs.chromia.com](https://docs.chromia.com/build/clients/postchain-clients/javascript-typescript/reference/)Content mirrored from the live docs
