Skip to content

Latest commit

 

History

History
221 lines (198 loc) · 11.7 KB

README.md

File metadata and controls

221 lines (198 loc) · 11.7 KB

XRouter and XCloud plugin samples

These scripts and configs provide sample XCloud plugins for use by Blocknet (and Scalaris) servicenodes. They are rudimentary demonstrators designed as templates or building blocks which can be adapted and customised by servicenode operators. They are really not hardened for production use.

Providing XRouter and XCloud services does require some technical understanding and competence. Essential skills include

  • be able to google stuff,
  • use the linux command line,
  • follow instructions,
  • think for yourself.

For background information refer to the servicenode documentation and in particular the XRouter and XCloud sections.

XCloud plugins may be of two types: RPC and Docker. There are examples here of both types.

RPC plugins

RPC plugins make RPC calls to a daemon (most likely) running on the same server as the servicenode. The target daemon deos not have to be for a coin supported by XBridge. Hence these examples include RPCs for Crown (CRW), Merge (MERGE) and Alqo (XLQ) which are not (currently) supported by XBridge and not tradeable on BlockDX.

Plugin Description
block_blockchaininfo Execute BLOCK getblockchaininfo
btc_blockchaininfo Execute BTC getblockchaininfo
crw_blockchaininfo Execute CRW getblockchaininfo
crw_mempoolinfo Execute CRW getmempoolinfo
crw_mnlist Execute CRW masternodelist
crw_peerinfo Execute CRW getpeerinfo
crw_snlist Execute CRW systemnodelist
crw_txoutsetinfo Execute CRW gettxoutsetinfo
dash_blockchaininfo Execute DASH getblockchaininfo
dgb_blockchaininfo Execute DGB getblockchaininfo
doge_blockchaininfo Execute DOGE getblockchaininfo
ltc_blockchaininfo Execute LTC getblockchaininfo
merge_mempoolinfo Execute MERGE getmempoolinfo
merge_mncount Execute MERGE getmasternodecount
merge_mnlist Execute MERGE listmasternodes
merge_peerinfo Execute MERGE getpeerinfo
rvn_blockchaininfo Execute RVN getblockchaininfo
scc_blockchaininfo Execute SCC getblockchaininfo
sys_blockchaininfo Execute SYS getblockchaininfo
xlq_mempoolinfo Execute XLQ getmempoolinfo
xlq_mncount Execute XLQ getmasternodecount
xlq_mnlist Execute XLQ listmasternodes
xlq_peerinfo Execute XLQ getpeerinfo

RPC plugins offer only very limited functionality and no possibility of "massaging" the results within the plugin. Any massaging required must be performed at the client side after receiving the RPC result. For example, the getblockchaininfo calls here all provide access to the relevant blockchain size on disk but it is embedded in a bunch of other information. In lieu of an actual xxx_sizeondisk service a client can instead

blocknet-cli xrService btc_blockchaininfo | grep size_on_disk

which still needs a little bit of post-processing. Alternatively, if jq is installed the client can

blocknet-cli xrService btc_blockchaininfo|jq -r .reply | jq .size_on_disk

Docker plugins

Docker-type plugins can be much more functional than RPC ones but are more complicated to create, deploy and configure. These examples are all very simple wrappers around well-known 3rd-party APIs.

Plugin Description
AlexaRank Find the Alexa page rank for a URL
bitly Generate a bit.ly shortened URL
cgprice Get the current CoinGecko price for a coin or token
cgpricej Get extended current CoinGecko price information for a coin or token
indexer Run pre-packaged sample queries against the Blocknet/Avalanche indexer
weather Get the current weather information for a given location
yfprice Get the current price for a Yahoo! Finance asset
yfticker Get the current ticker for a Yahoo! Finance asset

The wrappers can be written in any language you're comfortable with. They can be made as generic or as specific as you want and are competent to code. These examples use bash or Python.

Most APIs like those used here require registration and use of an API key. They generally perform rate-limiting and provide different feature sets depending on how much you want to pay for a subscription.

Plugins don't have to call external APIs; they can get data from any source, such as local hardware (eg: weather station, TNC, true random number generator, IoT appliance), local database, ...

Deployment

prerequisites

  1. Install Docker if not already installed. You will have already done this if yours is an EXR servicenode. If not, there are hundreds of examples showing how to do so on the internet. Your servicenode hosting provider may have customised instructions which best suit your setup. Digital Ocean provide a number of good tutorials which are widely applicable, for example https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-on-ubuntu-18-04
  2. Install Python >= 3.6 if not already installed and you want to be able to tinker with/test the plugins outside of a Docker container. Using your distro's package manager will be the easiest way to install Python3 but you might get an old version this way. Use your favourite search engine to find the best instructions for your particular environment.

using tarfile

  1. Download the archive to your servicenode plugins directory, eg:

    cd ~/.blocknet/plugins
    wget https://github.com/walkjivefly/xcloud-plugins/archive/refs/tags/v1.0.1.tar.gz
    tar -xvf xcloudsample
    
  2. Customise the API keys in individual plugins. These plugins require a personal API key:

    Plugin API key available from
    AlexaRank https://aws.amazon.com/marketplace/pp/prodview-w6qmxismbbs7u?ref_=srh_res_product_title
    bitly https://support.bitly.com/hc/en-us/articles/230647907-How-do-I-generate-an-OAuth-access-token-for-the-Bitly-API-
    weather https://openweathermap.org/appid
  3. The cgprice, cgpricej, yfprice and yfticker plugins don't (currently) require a personal API key.

  4. Customise the target address in the indexer plugin. This demonstrates that the actual service may be provided by some machine other than the servicenode host itself.

  5. Install the xcloudsample Docker image. This comprises a minimal Ubuntu image with curl and just enough Python3 to run the examples1 but it does not include the actual plugin scripts.

    docker pull walkjivefly:xcloudsample
    

    Check what the previous command did and make a note of the image id

    docker images
    

    The result will be something like

    REPOSITORY                 TAG       IMAGE ID       CREATED        SIZE
    walkjivefly/xcloudsample   latest    baaf7fd4c851   16 hours ago   630MB
    
  6. Create an actual container from the image and leave it running in the background.

    docker run -it -d --name xcloudshell baaf7fd4c851 bash
    
  7. Copy the plugin scripts to the container

    docker cp AlexaRank xcloudshell:/usr/local/bin
    docker cp bitly xcloudshell:/usr/local/bin
    docker cp cgprice xcloudshell:/usr/local/bin
    docker cp cgpricej xcloudshell:/usr/local/bin
    docker cp indexer xcloudshell:/usr/local/bin
    docker cp weather xcloudshell:/usr/local/bin
    docker cp yfprice xcloudshell:/usr/local/bin
    docker cp yfticker xcloudshell:/usr/local/bin
    
  8. Check they're really there by

    docker exec xcloudshell ls -l /usr/local/bin
    

    The output should be something like

    total 48
    -rwxr-xr-x 1 1000 1000  278 Jun 19 10:43 AlexaRank
    -rwxr-xr-x 1 1000 1000 1753 Jun 20 16:43 bitly
    -rwxr-xr-x 1 1000 1000 2569 Jun 19 11:24 cgprice
    -rwxr-xr-x 1 1000 1000 2787 Jun 19 11:24 cgpricej
    -rwxr-xr-x 1 root root  225 Jun 18 20:22 chardetect
    -rwxr-xr-x 1 root root  220 Jun 18 20:22 f2py
    -rwxr-xr-x 1 root root  220 Jun 18 20:22 f2py3
    -rwxr-xr-x 1 root root  220 Jun 18 20:22 f2py3.6
    -rwxr-xr-x 1 1000 1000  671 Jun 19 11:24 indexer
    -rwxr-xr-x 1 root root  209 Jun 18 20:22 sample
    -rwxr-xr-x 1 1000 1000  133 Jun 19 11:24 weather
    -rwxr-xr-x 1 1000 1000 1717 Jun 19 11:24 yfprice
    -rwxr-xr-x 1 1000 1000 1711 Jun 19 11:24 yfticker
    

    and that they do what they're supposed to, for example by

    docker exec xcloudshell AlexaRank bbc.co.uk
    docker exec xcloudshell bitly https://www.ibm.com/
    docker exec xcloudshell cgprice btc eur
    docker exec xcloudshell indexer pairs
    docker exec xcloudshell weather kathmandu
    docker exec xcloudshell yfprice GBPUSD=X
    docker exec xcloudshell yfticker ORCL
    
  9. Commit the changes to the image so if anything destructive happens to the container you can recreate it without having to copy the plugins in again.

docker commit -m "Populated and ready to use" xcloudshell
  1. Add chosen plugins to your xrouter.conf. Plugins can inherit the default [main] settings or you can customise them on a per-plugin basis. For example, add the following line to enable all of the example plugins
plugins=AlexaRank,bitly,cgprice,cgpricej,cgtest,indexer,yfprice,weather,yfticker,btc_blockchaininfo,block_blockchaininfo,dash_blockchaininfo,dgb_blockchaininfo,doge_blockchaininfo,ltc_blockchaininfo,rvn_blockchaininfo,scc_blockchaininfo,sys_blockchaininfo,xvg_blockchaininfo,crw_mnlist,crw_snlist,crw_txoutsetinfo,crw_blockchaininfo,crw_mempoolinfo,crw_peerinfo,xlq_mncount,xlq_mnlist,xlq_mempoolinfo,xlq_peerinfo,merge_mncount,merge_mnlist,merge_mempoolinfo,merge_peerinfo

Unless you are running DASH, DOGE, LTC, RVN, SCC, SYS, XVG, CRW, XLQ and MERGE you will need to choose only the plugins your servicenode can support. This is also your opportunity to extend the functionality of the XRouter network by creating xxx_blockchaininfo plugins for other coins accessible from your servicenode, or to create additional RPC plugins for other commands you think may be useful.

  1. Reload the XRouter config and check that the new services are listed in the servicenode status, for example
    blocknet-cli xrReloadConfigs
    true
    {
      "alias": "SN01",
      "tier": "SPV",
      "snodekey":  "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "address": "Bxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "timelastseen": 1624024544,
      "timelastseenstr": "2021-06-18T13:55:44.000Z",
      "status": "running",
      "services": [
        "BLOCK",
        ...
        "xrs::AlexaRank",
        "xrs::bitly",
        "xrs::block_blockchaininfo",
        "xrs::btc_blockchaininfo",
        "xrs::cgprice",
        "xrs::cgpricej",
        "xrs::crw_blockchaininfo",
        "xrs::crw_mempoolinfo",
        "xrs::crw_mnlist",
        "xrs::crw_peerinfo",
        "xrs::crw_snlist",
        "xrs::crw_txoutsetinfo",
        "xrs::dash_blockchaininfo",
        "xrs::dgb_blockchaininfo",
        "xrs::doge_blockchaininfo",
        "xrs::indexer",
        "xrs::ltc_blockchaininfo",
        "xrs::merge_mempoolinfo",
        "xrs::merge_mncount",
        "xrs::merge_mnlist",
        "xrs::merge_peerinfo",
        "xrs::rvn_blockchaininfo",
        "xrs::scc_blockchaininfo",
        "xrs::sys_blockchaininfo",
        "xrs::weather",
        "xrs::xlq_mempoolinfo",
        "xrs::xlq_mncount",
        "xrs::xlq_mnlist",
        "xrs::xlq_peerinfo",
        "xrs::xvg_blockchaininfo",
        "xrs::yfprice",
        "xrs::yfticker"
       ]
    }
    
  2. Tell the world what you've done!

Footnotes

  1. For security reasons you may prefer to build your own container using the Dockerfile found in the archive. This and the requirements.txt were used to create the xcloudsample image.