TEEX Developing Tools

TEEX developing tools can be used to develop and invoke TEEX secure services, TEEX data uploader, etc. We embed all the tools as well as several demos, in a pre-configured Docker image. We use the container to distribute our tools because that the container can be easily executed on different Operating Systems, which allows us to update and release our tools timely.

How to install Docker on your Operating System can be found:

Downloading Tools

After installing the Docker, the latest version of TEEX developing tools can be downloaded by:

 $ docker pull teextestnet/teex-tools

If the tools are downloaded correctly, you can find teextestnet/teex-tools when input docker images

Starting Tools

You can start the development environment by running the teextestnet/teex-tools images and then develop the service inside the container.

 $ docker run -it teextestnet/teex-tools

After you exit the container by exit, you can re-enter the container by executing:

 $ docker start -i $(CONTAINER_NAME)

The CONTAINER_NAME is the name of the started container and can be got by executing docker ps -a.

TEEX supports native Python, so the developer may want to use his existing Python code as TEEX secure service. To do this, developer needs to copy existing Python code into the container. There are two methods to do this. First, the developer can directly copy some files into container, by executing:

 $ docker ps $(SOURCE_FILE) $(CONTAINER_NAME):$(TARGET_PATH)

The SROUCE_FILE is the files you want to copy into the container, and the TARGET_PATH is the target directory inside the container, which you want to copy the file to. The developer can also mount a host directory into a container when start a container, by executing:

 $ docker run -it -v $(SOURCE_DIR):$(TARGET_DIR) teextestnet/teex-tools

More about how to use docker can be found in Docker Command-Line Interfaces (CLIs).

Note

Every time you use docker run, it will start a new container based on the specific docker image and will not contain any of your modification on the previous container. To re-enter an existing container, you can use docker start.

Existing Tools

There are three basic TEEX developing tools in the docker image:

  • teex-upload, which is used to upload data used by secure services in TEEX TestNet.
  • teex-debug, which is used to test a secure service locally.
  • teex-deploy, which is used to deploy a secure service in TEEX TestNet.
  • teex-client, which is used to invoke a secure service in TEEX TestNet.

Apart from them, a developer can also use editor tools like vim or IDE like vscode to edit his secure service and directly debug the logic of secure service with python.

Tools Configuration

The TEEX developing tools use a configuration file to specify all the required information. The configuration file is located in /home/teex/.teex/config, in our container. There is already an example of configuration file:

 { "dispatcher_address": "testnet1.teex.io", "dispatcher_port": 9080, "service_manager_address": "testnet1.teex.io", "service_manager_port": 12000, "chainnode_address": "120.132.14.182", "chainnode_port": 9545, "teex_contract_address": "aeFC4E7143e8896D6aA67f5352372c7b0D233b9b", "token_contract_address": "B127af3CDE8ba755F42553c383Fd368BC4f8C25a", "wallet_public_key": "public key of your wallet", "wallet_private_key": "private key of your wallet" }

The first six attributes indicate the URLs of different components in TEEX TestNet, including dispatcher, service manager and blockchain node. Currently, there are four dispatchers which can be used, "testnet1.teex.io", "testnet2.teex.io", "testnet3.teex.io" and "testnet4.teex.io".

Since TEEX is a layer-2 network, it requires two contracts (teex_contract_address and token_contract_address) on the layer-1 blockchain. You also need to save your wallet information, including the public key and private key, in the configuration file. The wallet must have enough TEEX TestNet token. How to create your wallet and get TEEX TestNet token can be found in Quick Start.

Note

TEEX developing tools do not send the private key to your wallet outside the container. However, we also recommend that you should not reuse your existing wallet, which contains other cryptocurrency.

Uploading TEEX Secure Data

The data provider can upload his own data to TEEX secure storage, which will be further used by the secure services on TEEX TestNet. The uploading procedure includes four steps:

  1. Encrypting data and uploading it to the data storage;

  2. Generating data metadata information;

  3. Putting the data information on blockchain;

  4. Registering as a data provider in service manager.

To upload the data, the data provider should provide following information to the teex-upload:

  • data file: which is a text file that contains the native data.
  • data price: how much token should be paid to use this data.
  • aes key: the binary string that will be used to encrypt or decrypt to protect the data. Currently we support 128-bit AES key only.
  • data provider's public key (wallet address): the wallet used to receive the token paid by data user.
  • description: A brief description of the data.

To keep things simple, we provide a tool called teex-upload in the container to help the data provider to upload the data. All the required information should be parsed from a configuration file within json format, which looks like:

 { "data-file": "data.txt", "price": "20", "aes-key": "128 bits AES key, 16 bytes string", "public-key": "data provider public key, 40 bytes string (e.g., 0000...0000)", "desc": "Data Uploader Demo" }

After uploading the data, the teex-upload will get a unique data ID, data URL, data Hash, which can be used to further upload the data. The URL is used to fetch the uploaded data bu the service. the Hash will be verified to ensure the data integrity.

We use "data_upload_example" to show how to use teex-upload:

 $ cd ~/Demo/data_upload_example $ teex-upload -c upload.opt.conf

The output should be:

 --- Parsing configuration: done --- Starting data uploading --- Data price: 2 --- Data description: "data uploader demo" --- Connecting to service manager: done --- Building secure channel: done --- Sending request to service manager: done --- Calculating data hash: done --- Putting data information on blockchain --- Waiting the blockchain to register the data: done --- Data ID: f59389fdf4404beeab1095b9bfe302fd --- Data URL: teex://627306090abab3a6e1400e9345bc60c78a8bef57-952450ce94385a592135d76c75c95096384aca7fecf2fd1035cbe6cdd9badf7a --- Data Hash: c11c12c5528ea830535915529286851a9d3c07d3155493f72b6e77aca64430d7 --- Starting key uploading --- Connecting to service manager: done --- Building secure channel: done --- Sending key to service manager: done

Debugging TEEX Secure Service

Currently, developer can write TEEX secure service with native Python (Python2.7), and easily debug the logic of the service with Python runtime in the container. Beside the Python runtime, we also provide a debug tool teex-debug in the container to first check whether the service satisfies the requirements of TEEX TestNet and then execute the service locally. Details of the requirements can be found in Writing Service in Native Python By typing teex-debug --help, you can get the help information of teex-debug.

 Usage: teex-debug [options] Options: -f , --file= specify the service file -i  , --input= specify the service input -I , --inputfile= specify the service input in a single file -h, --help show this message

The option '-f' specifies the service code file, which is required. The option '-i' and '-I' specify the input of service. When using '-i', the input is parsed in command line. When using '-I', the input will be loaded from the specified input file.

We provide several demos in the container, you can try the teex-debug with "hello_world" demo, by executing:

 $ cd ~/service_demo/hello_world $ teex-debug -f hello_world.py -I input.txt

The output should be :

 --- Loading service file and arguments --- File name hello_world.py: done --- File name input.txt: done --- Checking service code: done --- Executing service locally: done --- Output: {'message': 'hello world!!\n'}

Note

The debug tool executes the secure service locally, without the protection provided by TEEX TestNet. To execute the service with the security guarantee, developers should deploy and invoke it on TEEX TestNet.

Warning

The debug tool cannot interact with the data provider. To obtain the data from the data provider, developers should invoke the service on the TEEX TestNet.

Deploying TEEX Secure Service

Developer can deploy secure service on TEEX TestNet. The deploying procedure includes three steps: generating service information, putting service information on blockchain and registering service in service manager. To generate a service, developer should provide following information to the teex-deploy:

  • service script files: a list of python files that contain the service code, represented in the JSON format.
  • entry file: the python file where main entry function resides, should be only one file.
  • data id list: a list of data IDs which are published by data providers and will be used in this service. (Note: this field is optional)
  • service price: how much token should be paid to invoke this service.
  • worker fee rate: how much token of the service price will be paid to the worker, who executes the service.
  • service provider's wallet address: the wallet used to receive the token paid by service user.
  • service public/private key: which is used to generate the Proof of Work (PoW) information for each invocation of the service.
  • description: A short description of the service.

To keep things simple, we provide a tool called teex-deploy in the container to help the developer deploying the service. All the required information should be parsed from a configuration file within json format, which looks like :

 { "service-files": [ {"filename": "hello_world.py"}, {"filename": "hello_lib.py"} ], "entry-file": "hello_world.py", "data-list": [ {"data-id": "32 bytes string"}, {"data-id": "32 bytes string"}, {"data-id": "32 bytes string"}, ], "price": "2", "worker-feerate": "1", "private-key": "service public key, 40 bytes string (e.g., 0000...0000)", "public-key": "service private key, 64 bytes string", "desc": "Hello World Demo" }

After deploying the service, the teex-deploy will get a unique service ID, which can be used to further invoke the service.

We use "data_example" to show how to use teex-deploy:

 $ cd ~/Demo/data_example $ teex-deploy -c deploy.opt.conf

The output should be:

 --- Starting Service Deployment --- Service script list: --- Service script entry: hello_world.py --- Service script file[0]: hello_world.py --- Service script file[1]: hello_lib.py --- Service data list: --- Data ID[0]: c5b6605490f94b1688159ca457815a56 --- Data ID[1]: c5b6605490f94b1688159ca457815a56 --- Data ID[2]: c5b6605490f94b1688159ca457815a56 --- Service price: 2 --- Service worker-feereate: 1 --- Service description: "Hello World Demo" --- Parsing configuration: done --- Preparing service info --- Loading service script: done --- Calculating service hash: done --- Putting service information on blockchain --- Connecting to blockchain: done --- Sending service to blockchain: done --- Waiting the blockchain to confirm the service: done --- Sending service to service manager --- Connecting to servier manager: done --- Building secure channel: done --- Sending request to service manager: done --- Getting response: done --- Deploy Result: --- Service ID: ec33d75929374574ba04b2248473b53f

Invoking TEEX Secure Service

A user can invoke an existing service on TEEX TestNet with its service ID by issuing a task. We also provide a tool called teex-client to help the user to do it, including creating the task on blockchain, invoking dispatcher to get a worker, sending task to the worker and getting the result. User needs to give three arguments to the teex-client, the service ID of target secure service, the input to invoke the service and how much token he will pay for this invocation.

To keep things simple, we provide a tool called teex-client in the container to help the developer invoking the service. All the required information should be parsed from a configuration file within json format, which looks like :

 { "service_id": "97a7907e0b264da7bde67c1d6c8a849d", "data-list": [ {"data-id": "32 bytes string"}, {"data-id": "32 bytes string"}, {"data-id": "32 bytes string"}, ], "input_file": "input.txt", "payment": "100" }

Here we use "data_example" as an example to show how to use teex-client. First, you should replace the "service_id" in client.opt.conf file with the ID got from teex-deploy. Put the desired "data-list" into the configuration file. Again note that this is not necessary if the service does use any data from data provider. Then you could invoke the service by:

 $ cd ~/Demo/data_example $ teex-client -c client.opt.conf

The output shoud be:

 --- Starting Service Invocation --- Service ID: 04ebb787188d43a0ab2c7660c788ef5f --- Task payment: 100 --- User input: hello world!! --- Data list: --- Data ID[0]: e8d6e3e7ca1b49bf89fd73f6acbd5ec2 --- Data ID[1]: e8d6e3e7ca1b49bf89fd73f6acbd5ec2 --- Data ID[2]: e8d6e3e7ca1b49bf89fd73f6acbd5ec2 --- Parsing configuration: done --- Creating task on blockchain --- Connecting the blockchain: done --- Calculating task hash: done --- Sending task to blockchain: done --- Waiting the blockchain to confirm the task: done --- Created task ID: c79f0a0e6a5148ad85b3b8a1033fba24 --- Invoking dispatcher --- Connecting to dispatcher: done --- Building secure channel: done --- Sending Request to dispatcher: done --- Getting response: done --- Got worker: 120.132.20.135:10000 --- Invoking worker --- Connecting to worker: done --- Building secure channel: done --- Sending request to worker: done --- Getting execution result: done --- Invocation result: --- Return message: {'message': 'String:hello world!!\nService Data:Welcome to use TEEX data uploader!Task Data:Welcome to use TEEX data uploader!'}