credits-js-lib v0.1.4

credits.js

A set of Javascript libraries that allow you to interact with a Credits node.

The intention is to keep the API similar to the Credits Core API.

Installation

npm install credits-js-lib
credits = require('credits-js-lib');

Usage

Wallets & Addresses

You can create a wallet and generate addresses, public keys, and private keys using the Wallet & Credential classes.

Creating a Wallet

// returns a Wallet instance
wallet = new credits.Credentials.Wallet();

Creating Credentials

// Create a new address
wallet.createCredential();
// Returns the Credential instance and adds it to the Wallet.credentials array.

// Create a new standalone Credential
credential = new credits.Credentials.Credential();

Using a Credential

// Components of a Credential
address = credential.address;
publicKey = credential.verifyKey;
privateKey = credential.signingKey;

// Signing a Byte array
credential = new credits.Credentials.Credential();
credential.sign(message);

// Signing a UTF8 or Hex String
credential = new credits.Credentials.Credential();
// returns [Signature, Message, PublicKey] in Uint8Array format
signature = credential.signUTF8(message);

// returns [Signature, Message, PublicKey] in Hex format
signature = credential.signHex(message);

// Verifying a signed message
// Returns `true` or `false`
valid = verifySignature(signatureBin, messageBin, publicKeyBin);
valid = verifyHexSignature(signatureHex, messageHex, publicKeyHex);

Transactions

Transactions are created by passing a Transaction data object in JSON format into the createTransaction function that lives in the Transaction object.

Transactions are defined by six fields:

• fqdn - This is the Fully Qualified Domain Name for a Credits module.
• network_id - The unique ID of the Blockchain Network you are interacting with.
• type - The registered Transaction Type on the Blockchain Network you are interacting with.
• proofs - A map of Address strings to Proof payloads that contains the authorization information for any Addresses that are required to authorize a given Transaction.
• data - A Key/Value JSON object containing the Transaction payload the Blockchain Network uses to apply the Transaction to the State.

Example Transaction JSON Object

This JSON object represents a Transaction created for use with the Balance-Net module hosted here: https://github.com/CryptoCredits/balance-kt

{
  "hash": "e076865b9e984447cb9f0aadf318a5cec909e4f07e400ddf644e9332a1b4c38d",
  "fqdn": "works.credits.balance",
  "network_id": "threashold-test-net",
  "type": 0,
  "data": {
    "nonce": 1310,
    "fromAddr": "1FG3LHD7kmQeZnCUXQJ756H2sGvAwiQCY",
    "amount": 100,
    "fee": 1,
    "toAddr":
    "bin"
  },
  "proofs": {
    "1FG3LHD7kmQeZnCUXQJ756H2sGvAwiQCY": {
      "type": "works.credits.core.single_address",
      "payload": {
        "verify_key": "2cd32af3ec59cac5e1b6acb2a6ed4116de68aa68ffa242d43229a1ca0a4c6c1a",
        "signature": "4bacf4333680508ba51de3c0fbba41005a55d7076e3ef4657e544060ba0cf30a690ad42c0104e577ba1b0930d487f757a1f8fedec9301a0dd12be4cd0e58f20f"
      },
      "metadata": {}
    }
  }
}

Populating a Transaction

Passing in a JSON object in the format specified above will return a populated Transaction object.

// txJSON is a Transaction data object in JSON format
transaction = new credits.Transaction.Transaction(txJSON);

Signing a Transaction

A success returns the signature in hex format and the Signature is stored the signature in the Transaction object. A failure leaves the Transaction object alone and returns false.

This is not implemented in the base Transaction class and must be defined in the context of a Proof type.

// Pass in a pre-populated credits.Credential object.
signature = transaction.sign(credential);

Connections & Node

A Connections object allows you to store a set of known Nodes which you can query against to determine State and Transaction history as well as submitting new Transactions to the Blockchain Network.

This querying is performed through a REST interface running on a Full Node in the Blockchain Network. Full specifications can be found at http://docs.credits.works.

At least one initial Node Host Address and Port must be known and can be sourced out of band or provided by the app developer. When developing a client for your Blockchain service, one ore more of these can be saved in a config file or served dynamically from a web server.

Basic Usage of the Connections Object

connections = new credits.Connections.Connections();

connections.addNode('localhost', 12500);

// All known Nodes live in an immutable List in the Connections Object.
node = connections.knownNodes.get(0);

// You can specify an optional API Version.
// The default is 'v1'.
node.apiVersion = 'v1';

Raw Node Queries

Basic GET and POST queries underly each of the Blockchain-specific queries exposed for the sake of usability.

These requests automatically version the query endpoint to the specified API Version of the Node.

// GET Request
node.get(endpoint, queryString, callback);

// POST Request
node.post(endpoint, formData, callback);

The callback is called with the body returned from the response.

Standardized Node Endpoints

To query a standard endpoint on a Credits Blockchain Node, you can use any of the following endpoints.

Node Status

// Returns the Node status and health check information.
status = node.status(callback);

Node State

// Returns the current Blockchain State assembled by the Node.
state = node.getState(callback);

Search State

// Returns a specific item from a Node's State for a given Address.
result = node.searchState(fqdn, type, address, callback);

Specific Transaction

// Find a specific Transaction by the Transaction Hash.
Transaction = node.getTransaction(transactionHash, callback);

Submit a New Transaction

// Submit a newly created and signed Transaction to a Node's Transaction Pool.
transactionHash = node.submitTransaction(transactionJSON, callback);

// This should be the JSON representation of the Transaction Object as defined above.

Authenticating to a Node

If you use Role Based Access to limit who is allowed to view State or History on your blockchain network, you can use session-based authentication to verify to a Full Node that you are allowed to access the data passed back by any specific request.

In order to authenticate to any given Node, you must pass in the Credential object that references the Public Key that you wish to authenticate as.

The Node will issue you a Challenge, that you will sign and POST back to the Node. The Node will then grant you an AuthToken which you will use in subsequent interactions.

This must be done for each Node you wish to communicate with in a given session.

// This will assign the authToken to the Node Object and then return the Authtoken.
authToken = node.authenticate(credential, callback);

Browser Usage

Browser usage is supported through using Browserify.