Taxa Network Python SDK Documentation

This library used to aid developers in building applications on the Taxa Network. It works with both Python 2.7 and Python 3.5+.

Apply for devnet access

Complete the registration here. And we will grant you access to the SDK shortly.

Installation

  1. Extract the SDK into a folder anywhere.
  2. On the command line, navigate to that folder and run the install script: python setup.py install.

Usage

The functionality of this SDK is accessable from the instances of the class TaxaRequest.

TaxaRequest

Wrapper class for the request going to a taxa server.

from taxa_sdk import TaxaRequest
request = TaxaRequest(identity='/path/to/identity.taxa')

The identity argument is the path to your identity file that you either generated with a previous request, or if you're using this SDK for the first time, it will make one for you if the path you pass in is an empty file.

This "identity file" contains all the keys you need to use the taxa network, including the AES master keys, the client_cert and the client_key. You only ever need to have one identity file, unless you are using the taxa network as multiple users.

If you don't pass in an identity by leaving the constructor blank, a new identity file will be created for you in your home folder called taxa_default.taxa.

Sending your first request

Currently, there is a bug in the taxa_client binary that prevents the execution if that executable from anywhere other than the directory taxa_client is found in. So all SDK execution should always be done from within the taxa_client folder. Otherwise you'll get a cryptic error.

from taxa_sdk import TaxaRequest
request = TaxaRequest()
response = request.send(
    code_path="/path/to/tsetvice.py",
    function="submit",
    data="{'amount': 3500000}"
)

Passing in client_cert and client_key

If you already have a keyfile/cert, you can pass those in like so:

request = TaxaRequest(
  client_key_path="/path/to/my.key",
  client_cert_path="/path/to/my.cert"
)

If the client_cert and client_key have the same filename except for the extension and are in the same folder, then you may only pass in client_key. When the attestation process commences, the master key used for AES encryption of data between you and the taxa server will be stored in my.[ip].aes. It takes the filename of the client_key and appends the ip and changes the extension to ".aes".

You can also pass in the path to the taxa_client executable, but keep in mind the bug in taxa_client prevents this from working unless you are in the same folder as taxa_client, so always using "./taxa_client" (The default) for now is recommended.

request = TaxaRequest(
  core_path="./taxa_client",
  verbose=True
)

Also, you van pass in verbose=True to get extra debug information printed to the screen.

Taxa Response

The response from the .send() method will be a dictionary object that looks like this:

{
  'version': '0.1',
  'content-type': 'text/plain',
  'response-code': '1000',
  'direction': '0',
  'public-message': '',
  'pyxa-version': '0.1',
  'content-transfer-encoding': 'base64',
  'encrypted_data': 'dF5sFeU8/GfxDsJiNaL4gms3',
  'decrypted_data': 'Your value is less than your opponent'
}

The response from the server decrypted with your AES key can be found in the decrypted_data section of the response.

Other request parameters

You can set the ip instance variable to a string depicting the IP address of the server you want to connect to. This feature is helpful for testing. If this argument is left off, then the SDK will route the request the request to a random taxa server.

Manual Decrypting Responses

If you've received a response from the taxa server through other means (like you called taxa_client separately, then you can decrypt the response manually using the decrypt_data method of TaxaRequest.

>>> request = TaxaRequest(
  keyfile_path="/path/to/keyfile.key",
  cert_path="/path/to/client_cert.cert"
)
>>> request.decrypt_data('dF5sFeU8/GfxDsJiNaL4gms3')
'Your value is less than your opponent'

Converting a taxa identity file into individual files

If you are using the taxa identity format (which is the default), then all of your keys, both private and public are stored into a single file. This makes it hard to share your public key because you can't just send your taxa identity to another person, because they'll get your private keys too.

You can run the key_manager.write_key_to_file() method to write just the cert file to a separate file for sharing:

>>> from taxa_sdk.key_managers import IdentityKeyManager
manager = IdentityKeyManager("/path/to/identity.taxa")
manager.write_key_to_file("client_cert")

The key_manager object can also be accessed through the TaxaRequest class:

>>> from taxa_sdk import TaxaRequest
request = TaxaRequest("/path/to/identity.taxa")
request.key_manager.write_key_to_file("client_cert")

Then the cert will be written to a file located /path/to/identity.taxa.cert. You can pass in either "client_cert", "client_key", or "aes".

Exceptions

If the SDK throws an exception that descends from taxa_sdk.exceptions.TaxaException, then it means you probably made an mistake, and you need to consult the documentation. If the exception that gets raised is not descended from TaxaException, then you might have encountered a bug in the SDK, and you should report the issue to the developers.

Running tests

To run the tests for this module, run the following command:

python -m taxa_sdk.tests