@chromia/postchain-client

Postchain client

Example:

let crypto = require("crypto");
let secp256k1 = require("secp256k1");

// 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);

// 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([signerPubKeyA, 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 public key is optional. If omitted it will be calculated
// from the private key. It is recommended to include the public
// key for performance reasons.
req.sign(signerPrivKeyA, signerPubKeyA);

// ... or by the addSignature() function
let bufferToSign = req.getBufferToSign();
// Sign the buffer externally
let signatureFromB = askUserBToSign(bufferToSign);
// 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);
  }
});

// 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
let queryObject = { type: "findStuff", text: "arg1" };
let resultHandler = (error, result) => {
  if (error) {
    console.error(error);
    return;
  }
  if (result.hits == 0) {
    // Poll every 2 seconds
    setTimeout(gtx.query(queryObject, resultHandler), 2000);
  }
  console.log(JSON.stringify(result));
};
gtx.query(queryObject, resultHandler);

// This will make a request with a single operation
// and a single signature.
req = gtx.newTransaction(blockchainRID, [signerPubKeyA]);
req.fun1("arg1");
req.sign(signerPrivKeyA);
req.send((error) => {
  if (!error) {
    done();
  }
});

function sha256(buffer) {
  return crypto.createHash("sha256").update(buffer).digest();
}

// This is to demonstrate that you can use external signing
// mechanisms.
function askUserBToSign(buffer) {
  // The signed digest is a double sha-256
  var digest = sha256(sha256(buffer));
  return secp256k1.sign(digest, signerPrivKeyB).signature;
}

A very simple backend for the above client might look like this:

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)"
  );
};

// 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");
  },
  fun2: async function (conn, tx_iid, call_index, signers, intArg1, intArg2) {
    console.log("fun2 called in backend");
  },
};

module.exports.backendQueries = {
  findStuff: async function (readOnlyConn, queryObject) {
    console.log("Search for " + queryObject.text);
    if (queryObject.text === "giveMeHits") {
      return { hits: 4 };
    }
    return { hits: 0 };
  },
};

GTX architecture

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.

User
 |
 | req.fun1('arg1', 'arg2');
 | req.fun2('arg1'); req.sign(privKeyA); req.send(err => {})
 v
GtxClient
 |
 | <Buffer with serialized message>
 v
RestClient
 |
 | 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

• 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.

Release notes

1.0.0

• New logger accessible in index.ts.
• Enable the client to connect to a blockchain through multiple nodes running the blockchain.
• Load balancing by randomly distributing transactions and queries between nodes.
• Retry policy added for HTTP request to the blockchain.
• Enables you to discover the nodes running your blockchain by querying D1 with your dapp´s blockchain RID. Read more in the Chromia client providers Readme.

Breaking changes:

• Previously a rest client was initialized with one string containing the address of the node running your blockchain. Now an instance of the rest client is initiated with a list of strings representing the addresses of the nodes where your dapp is running.
• Previously a rest client query was called with two parameters; queryName and queryObject. Now this call only takes one parameter called queryObject, which is defined as: { type: string; [arg: string]: RawGtv; } where type is what previously was called query name.

0.*.*

Early version of the postchain-client written in javascript.