postchain-client 1.7.0 → 1.8.0

package/README.md

@@ -13,7 +13,11 @@ Firstly, import the required libraries.
 ```typescript
 import crypto from "crypto-browserify";
 import secp256k1 from "secp256k1";
-import { encryption, createClient, newSignatureProvider } from "postchain-client";
+import {
+  encryption,
+  createClient,
+  newSignatureProvider,
+} from "postchain-client";
 ```
 
 Then, create some dummy keys.
@@ -41,7 +45,7 @@ const chromiaClient = await createClient({
 });
 ```
 
-Connecting to a network is achieved through the Directory System Chain. The `directoryNodeURLPool` property accepts an array of URLs to system nodes running the directory chain. This directory chain is automatically queried to determine the URLs of the nodes in the network running the target dapp.
+Connecting to a network is achieved through the Directory System Chain. The `directoryNodeUrlPool` property accepts an array of URLs to system nodes running the directory chain. This directory chain is automatically queried to determine the URLs of the nodes in the network running the target dapp.
 
 ```typescript
 const chromiaClient = await createClient({
@@ -49,11 +53,15 @@ const chromiaClient = await createClient({
   blockchainRid,
 });
 ```
+
 ### Failover strategies
+
 When initializing a client, you have the option to configure the failover strategy for the client. Additionally, you can modify certain 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. This means that if a client error occurs, such as an
 invalid query parameter, the request strategy will not retry the query.
@@ -61,12 +69,14 @@ However, if a server error occurs, such as a timeout or internal server
 error, the request strategy will retry the query on another node.
 
 #### 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 retrying on server error.
 
 #### Single Endpoint
+
 The Single Endpoint request strategy will not retry on another node.
 
 ## Queries
@@ -110,7 +120,7 @@ type ReturnType = {
   foobar: string;
 };
 
-const result = await chromiaClient.query<ArgumentsType, ReturnType>(
+const result = await chromiaClient.query<ReturnType, ArgumentsType>(
   "get_foobar",
   {
     foo: 1,
@@ -119,6 +129,22 @@ const result = await chromiaClient.query<ArgumentsType, ReturnType>(
 );
 ```
 
+### 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.
@@ -129,31 +155,35 @@ const signatureProviderA = newSignatureProvider({ privKey: signerPrivKeyA });
 
 ### Simple Transaction
 
-The `signAndSendUniqueTransaction` function streamlines the process of sending a transaction 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 that includes a status code, status, and transactionRID. 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`.   
+The `signAndSendUniqueTransaction` function streamlines the process of sending a transaction 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 that includes a status code, status, and transactionRID. 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
-);
+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
-);
+const { status, statusCode, transactionRID } =
+  await chromiaClient.signAndSendUniqueTransaction(
+    {
+      name: "my_operation",
+      args: ["arg1", "arg2"],
+    },
+    signatureProviderA
+  );
 ```
 
 ### Signing a Transaction
@@ -183,6 +213,7 @@ const receipt = await chromiaClient.sendTransaction({
   args: ["arg1", "arg2"],
 });
 ```
+
 ### Sending a Signed Transaction
 
 ```typescript
@@ -236,25 +267,30 @@ const signedTx = await chromiaClient.signTransaction(
 
 const receipt = await chromiaClient.sendTransaction(signedTx);
 ```
+
 ## PromiEvent
+
 When using functions that involve sending a transaction, you have the option to 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 or any potential errors. Moreover, it emits an event when a transaction is sent, providing you with the ability to listen for 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")
-          });
+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(buffer) {
-  // The signed digest is a double sha-256
-  var digest = sha256(sha256(buffer));
+  // The signed digest is a sha-256
+  var digest = sha256(buffer);
   return secp256k1.sign(digest, signerPrivKeyB).signature;
 }
 ```
@@ -267,7 +303,9 @@ const signatureProviderB = {
   sign: askUserBToSign,
 };
 ```
+
 ## ICCF
+
 Creates an [ICCF](https://docs.chromia.com/overview/cross-chain-communication) (Inter-Chain Communication Framework) proof transaction. 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 should be accompanied by the proof should be added to this transaction object. The transaction can then be signed and posted to the target blockchain.
 
 ```typescript
@@ -290,14 +328,17 @@ const { iccfTx, verifiedTx } = createIccfProofTx(chromiaClient, txToProveRID,txT
 `iccfTx` is a transaction object with an operation called `iccf_proof` with argument containing the composed proof. To this transaction object you can now add the operation that will need the 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()
+const anchoringClient = getAnchoringClient();
 ```
+
 ## Architecture
 
 In the Postchain client, Generic Transactions (GTX) are used to simplify user implementations of Postchain. 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 more about GTX in the [docs](https://docs.chromia.com/category/gtx).
@@ -333,19 +374,20 @@ Backend
 ## Contributing to the Project
 
 ### Run tests
+
 Unit tests:
 
-``npm run test:unit``
+`npm run test:unit`
 
 Integration tests:
 
 1. Make sure a postgres database is running. Read more [here](https://docs.chromia.com/getting-started/dev-setup/database-setup).
 2. Start blockchain
 
-    ```cd resources``` 
+   `cd resources`
 
-    ```chr node start --wipe```
+   `chr node start --wipe`
 
 3. Run tests
 
-    ```npm run test:integration```
+   `npm run test:integration`