Skip to content
kdb+ wrapper library for interacting with the factom client (factomd) and wallet (factom-walletd) applications via the v2 REST APIs. See the Factom API reference documentation here
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples
images
lib
tests
LICENSE
README.md

README.md

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

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
jlucid@kx.com
https://github.com/jlucid

You can’t perform that action at this time.