postchain-client 1.3.2 → 1.4.0

package/README.md

@@ -1,209 +1,286 @@
-# Postchain client
-
-## Example:
-
-```javascript
-let crypto = require("crypto");
-let secp256k1 = require("secp256k1");
-let { encryption } = require("postchain-client")
-
-// Create some dummy keys
-let signerPrivKeyA = Buffer.alloc(32, "a");
-let signerPubKeyA = secp256k1.publicKeyCreate(signerPrivKeyA);
-let signerPrivKeyB = Buffer.alloc(32, "b");
-let signerPubKeyB = secp256k1.publicKeyCreate(signerPrivKeyB);
-
-// Create a simple signature provider.
-// This is the standard way of signing a message using the gtxClient,
-// and it can be used with the restClient too. Look further below for
-// more details on how to use it.
-let signatureProviderA = newSignatureProvider({privKey: signerPrivKeyA})
-
-// The lower-level client that can be used for any
-// postchain client messages. It only handles binary data.
-let restClient = require("postchain-client").restClient;
-
-// The higher-level client that is used for generic transactions, GTX.
-// This utilizes the GTX format described below to pass function calls
-// from the client to the postchain backend implementation.
-let gtxClient = require("postchain-client").gtxClient;
-
-// Each blockchain has a blockchainRID, that identifies the blockchain
-// we want to work with. This blockchainRID must match the blockchain RID
-// encoded into the first block of the blockchain. How the blockchainRID
-// is constructed is up to the creator of the blockchain. In this example
-// we use the linux command:
-// echo "A blockchain example"| sha256sum
-let blockchainRID = "7d565d92fd15bd1cdac2dc276cbcbc5581349d05a9e94ba919e1155ef4daf8f9";
-
-// Create an instance of the rest client and configure it for a specific set of
-// base urls and a blockchinRID. You may set an optional pool size for the connection pool,
-// default pool size is 10. Applications that do hundreds of requests
-// per second may consider setting this a bit higher, for example 100.
-// It *may* speed things up a bit. You may also set an opitional
-// poolinginterval in milliseconds, default is set to 500, a fail over
-// config wich include attemps per endpoint and attempt interval, default is 3 and 500.
-let rest = restClient.createRestClient([`http://localhost:7741`], blockchainRID, 5, 1000);
-
-// Create an instance of the higher-level gtx client. It will
-// use the rest client instance and it will allow calls to functions
-// fun1 and fun2. The backend implementation in Postchain must
-// provide those functions.
-let gtx = gtxClient.createClient(rest, blockchainRID, ["fun1", "fun2"]);
-
-// Start a new request. A request instance is created.
-// The public keys are the keys that must sign the request
-// before sending it to postchain. Can be empty.
-let req = gtx.newTransaction([signatureProviderA.pubKey, signerPubKeyB]);
-
-// call fun1 with three arguments: a string, an array and a Buffer
-req.fun1("arg1", ["arg2", [1, 2]], Buffer.from("hello"));
-// call the same function with only one argument
-req.fun1("arg1");
-// call fun2
-req.fun2(1, 2);
-
-// Signing can be done either through the sign() function ...
-// The signatureProvider method sign() will be called, and
-// it's expected to return the signature of the digest it's given
-// as input (of type Buffer). It needs to return the output of
-// secp256k1.ecdsaSign(...params).signature
-await req.sign(signatureProviderA);
-// You can also use this, if you don't need a signature provider
-// The second parameter is optional, it will be generated if not given
-//await req.sign(signerPrivKeyA, signerPubKeyA);
-
-// ... or by the addSignature() function
-let digestToSign = req.getDigestToSign();
-// Sign the buffer externally.
-let signatureFromB = askUserBToSign(digestToSign);
-// and add the signature to the request
-req.addSignature(signerPubKeyB, signatureFromB);
-
-// Finally send the request and supply an error callback
-req.send((error) => {
-  if (error) {
-    console.log(error);
-  }
+# Postchain Client
+
+Postchain Client is 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.
+
+## Usage
+
+The Postchain Client is compatible with both JavaScript and TypeScript. You can install the library from npm via https://www.npmjs.com/package/postchain-client.
+
+## 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 depends on the blockchain's creator. In this example, we use the Linux command: `echo "A blockchain example"| sha256sum`.
+
+```typescript
+const blockchainRID =
+  "7d565d92fd15bd1cdac2dc276cbcbc5581349d05a9e94ba919e1155ef4daf8f9";
+```
+
+Next, create a Chromia client instance and configure it with a specific set of base URLs, the `blockchainRID`, and so forth. If you connect to a local node, the `nodeURLPool` property accepts an array or a string of URLs to nodes running the target dapp.
+
+```typescript
+const chromiaClient = createClient({
+  nodeURLPool: "http://localhost:7740",
+  blockchainRID,
 });
+```
 
-// Now we can query Postchain. The backend must have a method
-// query method named "findStuff" (readOnlyConn, queryObject) that can
-// understand the query object and typically perform a search using
-// the database connection readOnlyConn. The backend query function
-// can return any serializable result object you chose
-gtx.query("findStuff", { text: "arg1" });
-
-// This will make a request with a single operation
-// and a single signature.
-req = gtx.newTransaction(blockchainRID, [signatureProviderA.pubkey]);
-req.fun1("arg1");
-await req.sign(signatureProviderA);
-req.send((error) => {
-  if (!error) {
-    done();
-  }
+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 = createClient({
+  directoryNodeURLPool: ["url1", "url2", "url3", "etc."],
+  blockchainRID,
 });
+```
 
-function sha256(buffer) {
-  return crypto.createHash("sha256").update(buffer).digest();
-}
+## Queries
 
-// This is to demonstrate that you can use external signing
-// mechanisms. It could be a complex function, requiring you
-// to sign from your phone, another device, or something else again
-function askUserBToSign(buffer) {
-  // The signed digest is a double sha-256
-  var digest = sha256(sha256(buffer));
-  return secp256k1.sign(digest, signerPrivKeyB).signature;
-}
+### Query Option 1
 
-// The complex signature process can, however, even be implemented in
-// a signatureProvider. Once you have a callback like the one above,
-// it's a simple matter of making a signature provider:
-let signatureProviderB {
-  pubKey: signerPubKeyB,
-  sign: askUserBToSign
-}
+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,
+  },
+});
 ```
 
-A very simple backend for the above client might look like this:
+### Typed Query
 
-```javascript
-module.exports.createSchema = async function (conn) {
-  console.log("Creating schema in backend");
-  await conn.query(
-    "CREATE TABLE IF NOT EXISTS example " +
-      "(id SERIAL PRIMARY KEY, stuff TEXT NOT NULL)"
-  );
+You can specify argument and return types for a given query in TypeScript.
+
+```typescript
+type ArgumentsType = {
+  foo: number;
+  bar: number;
+};
+
+type ReturnType = {
+  foobar: string;
 };
 
-// Example backend implementation that doesn't do anything but log the function calls
-module.exports.backendFunctions = {
-  fun1: async function (
-    conn,
-    tx_iid,
-    call_index,
-    signers,
-    stringArg,
-    arrayArg,
-    bufferArg
-  ) {
-    console.log("fun1 called in backend");
+const result = await chromiaClient.query<ArgumentsType, ReturnType>(
+  "get_foobar",
+  {
+    foo: 1,
+    bar: 2,
+  }
+);
+```
+
+## 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 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],
   },
-  fun2: async function (conn, tx_iid, call_index, signers, intArg1, intArg2) {
-    console.log("fun2 called in backend");
+  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
+);
+```
 
-module.exports.backendQueries = {
-  findStuff: async function (readOnlyConn, queryObject) {
-    console.log("Search for " + queryObject.text);
-    if (queryObject.text === "giveMeHits") {
-      return { hits: 4 };
-    }
-    return { hits: 0 };
+### 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);
+```
+
+### Advanced Transaction
+
+Create a transaction object.
+
+```typescript
+const tx = {
+  operations: [
+    {
+      name: "my_operation_1",
+      arguments: ["arg1", "arg2"],
+    },
+    {
+      name: "my_operation_2",
+      arguments: ["arg1", "arg2"],
+    },
+  ],
+  signers: ["signer1", "signer2"],
 };
 ```
 
-## GTX architecture
+You can modify the object to add operations or signers.
+
+```typescript
+tx.operations.push({
+  name: "my_operation_3",
+  arguments: ["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.
+
+```typescript
+const uniqueTx = chromiaClient.addNop(tx);
+```
+
+Sign and send the transaction.
 
-Generic transactions were developed to make it easier to make user implementations of Postchain.
-The user doesn't have to invent a binary format for it's transactions. With GTX you specify a
-set of functions that you will call from the client, and the GTX client will serialize the
-function calls, sign them and send to Postchain.
+```typescript
+const signedTx = await chromiaClient.signTransaction(
+  uniqueTx,
+  signatureProviderA
+);
+
+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")
+          });
+```
+## 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));
+  return secp256k1.sign(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,
+};
+```
+
+## 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).
 
 ```
 User
  |
- | req.fun1('arg1', 'arg2');
- | req.fun2('arg1'); req.sign(privKeyA); req.send(err => {})
+ | chromiaClient.sendTransaction()
+ |
  v
-GtxClient
  |
  | <Buffer with serialized message>
+ |
  v
-RestClient
  |
- | POST http://localhost:7741/tx {tx: 'hex encoded message'}
+ | 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
 ```
 
-The first four arguments to backend.fun1 are
+## Contributing to the Project
 
-- `conn` is a database connection that the backend function can use to query/update the database
-- `tx_iid` is the primary key of this postchain transaction.
-- `call_index`, 0 in this example. It's the index within the GTX of the current call
-- `signers`, all signers of this GTX. The signatures from these signers are already verified by
-  the GTX framework when the backend function is called.
+Please refer to the project's contribution guidelines to learn how you can help improve the Postchain client.