topdev0706 / blockchain-bitcoin-

qfactom

qfactom is a kdb+ wrapper library designed to interact with the Factom blockchain via the factomd client (factomd) and wallet (factom-walletd) REST APIs. The library allows records, in the form of kdb+ tables, lists etc, to be easily secured on the Factom blockchain through the use of simple q function. Entries made to Factom chains can serve as a Proof of Existence, enabling cryptographically secure audit trails to be constructed. Data stored on existing Factom chains, like those used to hold Stock market prices, can also be easily extracted and coverted to kdb+ table format, see example.

Combining the speed and scalability of kdb+, with the security and scalability of Factom, enables millions of records to be secured quickly and safely.

For install and usage instructions see wiki pages.

Functionality

• Transactions: Both factoid->factoid and factoid->entry credit, see Transactions.
• Chain creation: Create chains and make entries to those chains, see Creating Chains.
• Chain extraction: Extract all chain entries given a chain id, see Chain extraction.
• Receipts: Extract cryptographic proof that chain entries are secured with a single
  hash on the Bitcoin blockchain, see Anchors.
• Utilities: Check balances, block-height, transaction status, see State information.

Use cases

• Securing large IoT data sets, see Blockchain IoT Project and kdb+ mock example
• Securing private blockchains through the use of anchoring, see Blockchain Auditing
• Auditing and Compliance tool. For example, in the Mortgage industry, see Factom Harmony, Factom Apollo.
• Providing a proof of existence. Anchor hashes in the bitcoin blockchain can provide indisputable cryptographic proof that data was at a particular state at a given point in time, see PoE Explained
• Providing an open ledger for public data. Intrinio use the Factom blockchain to publish stock market prices every 15 minutes for 3000 US stocks, see Intrinio Article.
  Entry records are easily accessible via the Factom blockchain explorer. see Factom Market Data Entry
• Acting as a smart contract oracle, see Smart Contracts Article

Prerequisites

• kdb+ v3.4 or higher
• qutil - Required if you wish to load the library using qutil. If not, an alternative method is provided. See below.
• A factomd client and wallet application for the library to communicate with.

Installing

First set the environmental variable QFACTOM_HOME to where you placed the qfactom folder locally.

    $export QFACTOM_HOME=/home/test/library/qfactom/

Prior to loading the q scripts, a shared C library needs to be generated. Navigate to qfactom/lib/clibs/ and run

    $make curlLib        // This library is used to enable TLS support, see below

To load the qfactom library using qutil, follow the steps below.

Create a link named "qfactom" in the QPATH directory which points to qfactom/lib. This will enable .utl.require function to find the init.q file and load all q files. You can confirm the library is loaded correctly by checking that the .factomd and .factomwallet namespaces are present in the q session. Each namespace contains all the supported v2 API calls for the associated application.

    q).utl.require "qfactom"
    q)key `
    `q`Q`h`j`o`util`factomd`factomwallet    // .factomd and .factomwallet namespace loaded

Alternatively, the library can be loaded using the provided factomLoad.q script.

    $q $QFACTOM_HOME/lib/factomLoad.q
    q)key `
    `q`Q`h`j`o`util`factomd`factomwallet   

Configure

Hostnames

By default, qfactom assumes the factomd and factom-walletd applications are running on your localhost server. If they are hosted elsewhere, then run the following commands to change the default

    q).factomd.initHost["http://remotehost:8088/v2"]       // Change factomd host location
    q).factomwallet.initHost["http://remotehost:8089/v2"]  // Change factom-walletd host location

Security: Username and Password

If you are running factomd with username and password enabled, as shown below

    $./factomd -rpcuser <username> -rpcpass <password>

Then run the following command to ensure the authentication credentials are passed during the API calls

    q).factomd.initPass[username;password]

An easy way to confirm that the hostname and authentication credentials are set up correctly, is to execute the .factomd.properties and .factomwallet.properties function which will make a simple request for the version properties.

    q).factomd.properties[{x}]
    jsonrpc| "2.0"
    id     | 0f
    result | `factomdversion`factomdapiversion!("0.4.2.1";"2.0")

    q).factomwallet.properties[{x}]
    jsonrpc| "2.0"
    id     | 0f
    result | `walletversion`walletapiversion!("0.2.2.3";"2.0")

Incorrect username and password credentials will result in an error message being printed to stderr, and a dictionary object with key error being returned.

    q).factomd.properties[{x}]
    Error: illegal char U at 4 .Q.hpfact returned: 401 Unauthorized.

    error| "401 Unauthorized.\n"

Security: TLS Support

When factomd is started with TLS mode enabled, as shown below

    $./factomd -tls=true -selfaddr=domain.net,123.23.111.44

the calling program needs to specify the certificate file generated by factomd, see Security.
To enable TLS support within qfactom, pass the certificate file path to the .factomd.initTLS function.

     q).utl.require "qfactom"
     q).factomd.initTLS["/home/.factom/m2/factomdAPIpub.cert"]
     q).factomd.tlsEnabled   // Check it is enabled
     1b

When TLS is enabled, the .factomd.request function which submits queries to factomd and factom-walletd, will switch to using a C library function instead of the native .Q.hp function.

Tests

qspec tests are currently under construction.
See Test Folder

License

This code is licensed under an MIT license. See LICENSE for the full text.

Contact

Jeremy Lucid
[email protected]
https://github.com/jlucid