How To Setup the PegNet Ecosystem for Conversions and Transfers

Update (Nov. 6th, 2019): A new version of the PegNet Daemon has been released that lets you burn FCT by typing pegnetd burn [source address] [amount] .

It’s Monday, October 7th and today we are launching the most important aspect of PegNet: Transfers and Conversions or, in short, Transactions. They will be enabled starting with block 213237, with a planned official launch at 15:00 UTC.

What was once just an idea and a whitepaper is now reality. We are happy to release the PegNet Daemon, which will extend PegNet’s functionality to include these additional features:

  • Transfering any pegged asset to a different address (e.g. sending 10 pUSD to another person)
  • Converting pegged assets (excluding PEG) to a different pegged asset (e.g. converting 10 pFCT to pUSD)

What is the PegNet Daemon (pegnetd)?

To put it short: pegnetd is a small app that retrieves only the pegnet related data from a factom node and evaluates it to enable it to know the following:

  • The conversion rates produced by the oracle
  • Transfers and Conversions submitted to the transaction chain
  • FCT to pFCT conversions

Using that information, it builds a balance book that stores the balance of every address used in PegNet. This is what enables us to know which transactions are valid (ie: there are enough funds to cover it) and which are not. It is not, however, a wallet. That brings me to:

An Overview of the Ecosystem

All in all, four different apps are required for PegNet to work:

  • factomd the foundation that everything builds on
  • factom-walletd the wallet that holds your private keys
  • pegnet the miner that drives the oracle
  • pegnetd the (temporary) pegnet node described in this blog

They fit together something like this:

To do anything pegnet related, you will always need factomd and your wallet. If you want to mine PEG then you need the pegnet miner. If you want to transfer pegnet assets or convert pegnet assets or convert FCT to pFCT you will need the pegnetd node.

Here it should be noted that you do not have to run your own factomd node, you can use the Factom Open Node which is a public, load-balanced node. This comes with the downside that the initial sync will take much longer (more on that later), but the upside that you don’t have to install and configure your own node.

Setting up the pegnet node

Requirements are:

  • factomd and walletd installed
  • At least 2GB of RAM
  • At least 2GB of disk space (independent of factomd’s requirements)

The PegNet node is open source and we also provide several precompiled binaries. If you want to build it yourself, there are minimal instructions available. If you are compiling in windows, you will need Mingw32 installed, which I can only recommend to people who are very knowledgable in windows development.

The pegnetd node has two forms of operation: the node itself and also a command-line interface to interact with a running node. You can use the pegnetd tool to interact with a node that runs on a different computer as well. To run the node, you just run the pegnetd binary without any commands. To get an overview of what commands and flags are available, you can run pegnetd help.

Before you run it, you will also need to download the configuration file, which can be placed in the working directory or the pegnetd home folder of $HOME/.pegnetd (linux) or %USERPATH%\.pegnetd (windows). The settings you should pay attention to are:

  pegnetd = "http://localhost:8070"
  server = "http://localhost:8088/v2"
  wallet = "http://localhost:8089/v2"

The setting pegnetd is used when running pegnetd with commands (more on that below). If you are running the node on the same computer as the command, you can leave it as is. If you want to run commands for a node on a different computer, you will need to set the remote computer’s address here.

The setting server points to the factomd endpoint. The default assumes you are running a node on the same computer. If you want to use the open node, change this setting to https://api.factomd.net/v2.

The setting wallet points to your factom-walletd endpoint. The default assumes you are running the wallet on the same computer. Running a wallet on a different server is not recommended at this point.

All three of these settings are also available as flags --pegnet, --server, and --wallet respectively.

Running

At this point, you should have a running factomd node and wallet available. You start the pegnetd node by calling ./pegnetd_linux_amd64 (linux) or double-clicking pegnetd_windows_amd64.exe (windows).

If you are starting these apps for the first time, you will see the following lines:

time="2019-10-07T10:46:33+02:00" level=info msg="Opening database from 'YOUR_HOME_FOLDER/.pegnetd/mainnet/node.db'"
Reading ByteMap Table YOUR_HOME_FOLDER/.lxrhash/lxrhash-seed-fafaececfafaecec-passes-5-size-30.dat
Table not found, Generating ByteMap Table
Initializing the Table
Shuffling the Table
Pass 0

This creates the necessary data for PegNet’s LXR Hash, which takes up 1 GB of ram and 1 GB on disk. The process takes around 10 or more minutes and only has to be performed once. Once that is finished, you will see the following line:

time="2019-10-07T11:00:43+02:00" level=info msg="Listening on :8070..."

Which means the pegnet node has started and is now syncing with the factomd node. How long this takes depends on your setup:

  • Running factomd on the same computer or a local network: around 15 minutes
  • Using the Open Node: around 8 hours

You will see a progress report every 50 blocks, along the lines of: (please note that it may take up to 5 minutes for the first message to appear when using the open node)
time="2019-10-07T11:04:22+02:00" level=info msg="sync stats" avg=4.38150735s elapsed=3m39.0763675s height=206471 left=8h14m27.18626685s syncing-to=213242

Syncing only has to be done once. The next time you start the node, it will pick up where it left off. During normal operation, you won’t really see much output.

Disclaimer: New version releases may require you to delete your database file and restart the syncing process.

Using it

At this point, you should have the pegnet node, factom node, and walletd running. If you set up the config file, you can just type pegnetd [command], otherwise you should specify the endpoints via flags.

Balances

To find out all of the assets for a single address, use pegnetd balances [address]. Example:

$ ./pegnetd balances FA2CEc2JSkhuckEXy42K111MvM9bycUDkbrrHjd9bNkBfvPBSGKd
{"PEG":"94500","pADA":"0","pBNB":"0","pBRL":"0","pCAD":"0","pCHF":"0","pCNY":"0","pDASH":"0","pDCR":"0","pETH":"0","pEUR":"0","pFCT":"0","pGBP":"0","pHKD":"0","pINR":"0","pJPY":"0","pKRW":"0","pLTC":"0","pMXN":"0","pPHP":"0","pRVN":"0","pSGD":"0","pUSD":"0","pXAG":"0","pXAU":"0","pXBC":"0","pXBT":"0","pXLM":"0","pXMR":"0","pZEC":"0"}

Or if you just want to know the balance of a single asset, use pegnetd balance [asset] [address]. Example:

$ ./pegnetd balance PEG FA2CEc2JSkhuckEXy42K111MvM9bycUDkbrrHjd9bNkBfvPBSGKd
500 PEG

Conversion Rates

To find out what the conversion rate for a specific block is, use pegnetd get rates [height]. Example:

$ ./pegnetd get rates 213248
{"PEG":0,"pADA":3986305,"pBNB":1545711721,"pBRL":24652996,"pCAD":75055353,"pCHF":100616780,"pCNY":13989140,"pDASH":6921146241,"pDCR":1683254264,"pETH":17408778348,"pEUR":109722511,"pFCT":374658983,"pGBP":123047088,"pHKD":12748028,"pINR":1407341,"pJPY":936154,"pKRW":83490,"pLTC":5568180815,"pMXN":5108059,"pPHP":1928063,"pRVN":3154343,"pSGD":72375658,"pUSD":100000000,"pXAG":1746755401,"pXAU":150375939849,"pXBC":22778777950,"pXBT":794844321799,"pXLM":5981077,"pXMR":5527694809,"pZEC":3670185565}

Rates are in base e-8 (translation: put a decimal point to the left of the last 8 digits) and relative to pUSD, so a rate of pFCT = 374658983 means that 1 pFCT = 3.74658983 pUSD . A rate of pMXN = 5108059 means that 1 pMXN = 0.05108059 pUSD.

Status

To find out how far your node is synced, use pegnetd status. Example:

$ ./pegnetd status
{"syncheight":213248,"factomheight":213248}

syncheight refers to the height that the pegnetd node has data for, factomheight is the height of the factom network.

Transfer Pegged Assets

To transfer a pegged asset from your address to another address, use pegnetd newtx [ec address] [source address] [asset name] [amount] [destination address]. Example:

$ ./pegnetd newtx EC2Uktc9YFna7B21E7FJARxsz6dKRHUaPbaqvuXrZfsJJSWc4grW FA2jK2HcLnRdS94dEcU27rF3meoJfpUcZPSinpb7AwQvPRY6RL1Q pFCT 5 FA3debugfUqPcG9ZbQAkjU8BSSJTGJDC6bAQMBYe3zTB4BktZxko
transaction sent:
         EntryHash: 7924ab06d98b4f33b817cbd0239d709029d5bfd1a8c0ee1d318465606da9ba47
            Commit: afbc1c04b99ee7609b6398e263d5f2956003644b779e5a5cba5081e01b20f7cf

Please note that both the [ec address] and the [source address] must be in your wallet. The [destination address] does not need to be in your wallet.

Convert Pegged Asset

To convert one asset to another, use pegnetd newcvt [ec address] [source address] [source asset] [amount] [target asset]. Example:

$ ./pegnetd newcvt EC2Uktc9YFna7B21E7FJARxsz6dKRHUaPbaqvuXrZfsJJSWc4grW FA2jK2HcLnRdS94dEcU27rF3meoJfpUcZPSinpb7AwQvPRY6RL1Q pFCT 5 pUSD
conversion sent:
         EntryHash: 61cde7986aca94bcf7352926ecce045dd1d1d401fb581d814a3cd79212331939
            Commit: eacd58b652f7455c55aabaf25ec33c5fab9c51f119c043f7057606019165183f

Please note that both the [ec address] and the [source address] must be in your wallet.

At the time of writing, only one type of conversion is supported, which I described as Type A conversions in my previous blog. In the example above, 5 pFCT would be converted to 18.75 pUSD if the rate is 3.75.

Converting FCT to pFCT

The command is pegnetd burn [source address] [amount]. Example:

$ ./pegnetd burn FA2jK2HcLnRdS94dEcU27rF3meoJfpUcZPSinpb7AwQvPRY6RL1Q 10
Burn transaction sent to the network
Transaction: 4dbbff5a972a01b55562ed2a32a95271009acf956672f0c89caa42dc3fba10cc

The factoid address must be in your wallet. Please note that the entry credit address used to pay for the conversion is specified inside the miner’s defaultconfig.ini.

FAQ

Q: Why can’t I convert PEGs to other assets?
A: PEG is the reward for mining and is currently not listed at any exchange. Therefore there is no market price available to use for conversions. The plan is to launch it with an artificial price some time in the coming weeks but the specifics of that are not yet set in stone.

Q: What happens if my database is corrupted?
A: As I wrote in my original blog piece, PegNet uses a “trust yourself” method of reaching consensus. That means the data written on the Factom chain is immutable and it is up to everyone to interpret the data the same way. If your local database is lost or corrupted, the underlying data still exists and at worst you have to re-sync.

Final Thoughts

It may seem daunting at the moment to set up and perform these operations and I would agree with you. We are planning on rolling out better utilities over the coming weeks that will make it easier for everyone. What we have at the moment is only the first generation.

If you have any questions or encounter problems setting up pegnet, pegnetd, factomd, or the factom-wallet, please drop by the PegNet discord where plenty of people are eager to assist.