token-proxy v0.0.3

token-proxy

The token-proxy is a backend service for interacting with the TokenContract.

Description

The token-proxy is an API server that allows other services to work with its TokenContract while abstracting details about its implementation (except for the instance address). The TokenContract is included in this repository since the API server requires the contract artifacts (i.e. the ABI created during compilation). When an entity deploys any smart contract on the blockchain, it needs to be registered with the RegistryContract. The RegistryContract enables entities to lookup smart contract instance addresses.

The TokenContract can be deployed with the keystore-provider so that truffle can sign the contract deployment transaction using a keypair managed by the keystore component. Since, truffle usually expects that a keystore is built into the blockchain client (ganache, geth), which is not always the case, the keystore and keystore-provider components allow for flexibility to work with different blockchain clients.

Prerequisites

1. NodeJS: curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash - && sudo apt-get install -y nodejs
2. A blockchain node: https://github.com/ConsenSys/QuorumNetworkManager
3. The blockchain-proxy component: https://github.com/AdharaProjects/blockchain-proxy
4. The keystore component: https://github.com/AdharaProjects/keystore
5. Truffle version 4.1.14: npm install -g truffle@4.1.14

Installation

git clone git@github.com:AdharaProjects/token-proxy.git -o upstream
cd token-proxy
npm install

If the packages do not install properly, then run install with the following command to delete the old packages and the package-lock file:

rm -Rf node_modules package-lock.json; npm install

Usage

By default, this starts the token-proxy at port 5000 and assumes the blockchain-proxy is running at localhost:3000.

Deploy the token contract and then start. Additional networks can be added in truffle.js. The contract is deployed to the blockchain via the blockchain-proxy, which therefore requires the blockchain-proxy and keystore to be running, and account0 to have enough eth to pay gas.

truffle migrate --network keystore_provider
npm start

In the QuorumNetworkManager directory:

IP=127.0.0.1 ROLE=coordinator CONSENSUS=istanbul KEEP_FILES=true pm2 start setupFromConfig.js
adhara start blockchain-proxy
adhara start keystore
adhara list

In the token-proxy directory:

npm install
truffle migrate --network keystore_provider --reset 
npm start

Documentation

Api docs can be found at: http://localhost:5000/api-docs/

Configuration

Configuration can be found in the config.json file, or look at config.js for environment variables to use for configuration. Configuration parameters, defaults read from file, overrideable by setting environment variables:

1. apiServerAddress: The address where the token-proxy API server will be hosted, default = "http://localhost:5000", use API_SERVER_ADDRESS to override.
2. decimalPrecision: The decimal precision of amounts and balances in the TokenContract, default = 100, use DECIMAL_PRECISION to override.
3. blockchainProxyAddress: The address where the blockchain-proxy API server is hosted, default = "http://localhost:3000", use BLOCKCHAIN_PROXY_ADDRESS to override.
4. keystoreAddress: The address where the keystore API server is hosted, default = "http://localhost:12000", use KEYSTORE_ADDRESS to override.
5. blockchainNodeAddress: The address where the blockchain client RPC interface is hosted, default = "http://localhost:20010", use BLOCKCHAIN_NODE_ADDRESS to override.
6. blockchainNodeNetId: The blockchain network id to match for deployment, default (matches any network) = "*", use BLOCKCHAIN_NODE_NET_ID to override.
7. blockchainNodeGasPrice: The default gas price to use for contract deployments, default = "0", use BLOCKCHAIN_NODE_GAS_PRICE to override.
8. contractIdentifier: The contract identifier to use during deployment and registration of the TokenContract, default = "ACCOUNT1", use CONTRACT_IDENTIFIER to override.
9. automaticRegistration: Enable/disable automatic registration of a TokenContract deployment, default = false, use AUTOMATIC_REGISTRATION to override. When this parameter is set to true, it requires the following: a. An accessible registry-proxy API server to be running (as set in item no. 10) b. A registry contract to be deployed (and its address set in item no. 11) c. The entity (with its entity identifier set in item no. 12) to be registered with the registry contract c. The contract identifier (set in item no. 8) to be unique for this entity
10. registryProxyAddress: The address where the registry-proxy API server is hosted, default = "http://localhost:11000", use REGISTRY_PROXY_ADDRESS to override.
11. registryContractAddress: The address of an already-deployed registryContract instance, default = "", use REGISTRY_CONTRACT_ADDRESS to override.
12. entityIdentifier: The entity identifier of the entity registering a deployment of the smart contract, default = "Bank1", use ENTITY_IDENTIFIER to override.

Testing

Run the examples and tests to make sure they still work correctly. Use the adhara list command to check that the blockchain-proxy and keystore are running. Use the pm2 logs command to check status logging. Tests can be run in two modes. The unit test mode runs the tests using mock APIs and the integration tests runs the test using the components which it depends on.

Mode 1: Unit Tests

cd token-proxy
npm install
npm test

npm test is an alias for the npm run unit-tests command which runs the unit test scripts.

Mode 2: Integration Tests Running these tests requires at least 3 accounts in the keystore, and the first account having a non-zero balance.

cd token-proxy
npm install
truffle migrate --network keystore_provider --reset 
npm start

Open a new terminal to run the tests:

npm run integration-tests

Docker

Run

cd docker; docker-compose up -d

Wait a few moments and then execute the following:

docker logs docker_token-proxy_1

Run this command until it says 'Express server listening on port: 5000'. (There is no harm in trying to use the service before the blockchain node is running, it just won't work.)

Navigate to http://172.21.0.5:5000/api-docs (and http://172.21.0.4:3000/api-docs for the blockchain proxy) in your browser to interact with the api (chekc that your VPN is off) Run the tests with the following command:

docker exec -e BLOCKCHAIN_NODE_HOST=172.21.0.2 -e BLOCKCHAIN_PROXY_ADDRESS=http://172.21.0.4:3000 -e API_SERVER_ADDRESS=http://172.21.0.5:5000 docker_token-proxy_1 npm test

NB You can see commands that you can manually run by looking at the docker/docker-compose.yml file, they are displayed in the comments.