How to Factom

This guide is outdated, meaning some of the commands are incorrect.

I am Steven Masley, and I like Factom. That’s why I’m teaching you how to use and run it. This guide will make it easy for you to try out a blockchain technology.

I won second place in a global month long blockchain hackathon sponsored by Blockchain Education Network (BEN) by building a decentralized identification system on top on the Factom network. Through this, I landed an internship with the Factom team and have been in Austin throughout the 2016 summer.

To address the elephant in the room: I believe side chains serve a purpose for allowing more diverse use cases of blockchains, that can be implemented easier than through Bitcoin script. As the demand for blockchains increases, the Bitcoin network will have issues handling the new demand, potentially raising transaction fees. Side chains such as Factom allow incredible scaling of blockchain use, while reducing the load on the Bitcoin network.

How?

Writing data into the Bitcoin’s blockchain is difficult, expensive, and also considered spam. Factom is a side chain that alleviates congestion on the bitcoin blockchain while still taking advantage of Bitcoin’s hashing power by anchoring Factom’s chain into Bitcoin’s. Factom’s design allows for users to run a lite client, drastically reducing the amount of the blockchain needed to be downloaded to become synced to the current height, and not needing to download everything within the blockchain (Full nodes will still have to store everything).

Want to try it out?

Just like most blockchains out there, Factom has it’s own crypto currency called Factoids. Factoids can be bought, sold, and traded, but cannot be used to store anything on the Factom network. To use Factom, factoids must be burned into Entry Credits, which can then be used to store information in Factom. Why is is designed this way? It’s intentionally constructed like this to fixate the cost of an entry at ~$0.001. The conversion rate of factoids to Entry Credits will fluctuate with the price of factoids, so if the price sky rockets, then the conversion rate will rise as well. Entry Credits are not a crypto currency, or a currency at all. You cannot trade or sell Entry credits, you can only buy or use them. This is also an intentional design choice, as it lowers the incentive for malicious attacks, and allows a user to use Factom without ever touching a crypto currency if they are not comfortable using one. I will explain how to do the conversation later, but first we have to obtain some factoids.

Let’s Begin

1. As with any blockchain, we need the software to connect. You can download the required files from Factom’s github here

Once you have the executables, we will conduct the rest of the guide through the command line. If you are unfamiliar with command line commands, feel free to message me on slack for assistance, as command line familiarity will go a long way in the blockchain world.

cd /Applications/FactomApps
./factomd

That will start your Factom client and begin downloading the blockchain. This will take some time, so let’s get familiar with some other commands.

The current block height at the time of the guide

I like to open different tabs with cmd + t for the next steps. Open a new terminal window or tab, and we can use ./factom-cli for numerous commands.

./factom-cli help                         # shows the commands
./factom-cli get head                     # current directory block
./factom-cli get height                   # your current height

You can play around with some commands as you sync up, and check on your current height to see how close you are. In the mean time, we still need factoids…

If you are reading this, I hope I can assume you own some bitcoins, if you don’t, obtaining factoids will not be easy. You can exchange bitcoins for factoids on poloniex, bittrex, or find me on BEN’s slack channel and I can swing you some entry credits. An alternative is to buy some entry credits on Factom’s webstore (https://www.factom.com/entry-credits/).

So you may or may not have factoids at this point, but I’ll continue assuming you do and showing the proper steps to enter data into Factom. We need to create a wallet, and will use ./factom-cli to do so. We need to launch the wallet tool alongside our current ./factomd process. Open a new command line window/tab, navigate to your FactomApps folder, and type:

./fctwallet

Ok, now the wallet app is running, lets make a factoid wallet, and entry credit wallet.

./factom-cli generateaddress fct MyFctWallet
./factom-cli generateaddress ec MyEcWallet

It will output your addresses, but we don’t need to copy them down as they will be saved for you in a database folder on your computer. I do not advise making a wallet that may store a large amount of factoids this way, if you wish to create a wallet for larger storage, I may make a post later about how or you can message me on slack.

Loading your balances takes a few minutes the first time you make a wallet, as it has to go through the entire blockchain, so lets start that now.

./factom-cli balances

This will take a few minutes. In the meantime you can withdraw some factoids to your factoid address from your poloniex/bittrex account if you have some. Once your balances load and your factoids are transferred, we can continue to add an entry into Factom.

My output window from ./factom-cli balances

Here are my balances. I made a new wallet for the purposes of this demonstration, so please don’t send any factoids to this address, it will be deleted!

Now that we have our factoids, we can burn them to get some entry credits. To do so we need to send factoids to our entry credit address, so we must build the components of a transaction.

Read through it once before giving it a shot

Step 1: Create the transaction and name it:

./factom-cli newtransaction MyTransaction

* You can type in ./factom-cli transactions to check on your transaction*
Step 2: Add the amount of factoids you wish to burn: I will add 1

./factom-cli addinput MyTransaction MyFctWallet 1

Step 3: Add the ecoutput (‘ecoutput’ for entry credit transactions, ‘output’ for factoids transactions) to the entry credit address, make sure it is the same amount as the input:

./factom-cli addecoutput MyTransaction MyEcWallet 1

Step 4: Add the transaction fee, ‘./factom-cli getfee’ shows the current fee rate

./factom-cli addfee MyTransaction MyFctWallet

Step 5: Sign the transaction:

./factom-cli sign MyTransaction

Step 6: Our transaction is ready to broadcast to the network. You can do ./factom-cli transactions to double check your inputs. When you are ready to submit:

./factom-cli submit MyTransaction

Step 7: Now Wait… The transaction might hang for a few minutes as it checks your balances and other things. Just be patient, once submitted it will be confirmed in the next block. Factom blocks are 10 minutes long, and similar to Bitcoin will have different levels of confirmation. Without going into too much detail, when your transaction is successful, that means it was recognized, but is not confirmed. Once the 10 minute block is over (factom explorer to see blocks) your transaction is confirmed and the balances will be recognized. It gets further confirmed once it gets anchored into the bitcoin blockchain, then your transaction has full confirmation.
- Here is my transaction I sent to my entry credit wallet: http://explorer.factom.org/tx/1873697d6b59a0b14edde6c9425ce26bb5aa72bee67b771d0742cce10c8a72dc

After waiting up to 10 minutes, we have our entry credits!

Now we have the entry credits I’m sure you are ready to put a permanent immutable entry into Factom’s blockchain! That’s a lot of pressure, the whole world can see this unless you encrypt it, so let’s make it count.
We’re close, but need another short lesson on how Factom works. Entries in Factom live in chains. A chain is exactly what its name implies, it is a chain of entries. You don’t need to worry about the rest of the Factom structure, that can be learned another day. An Entry has 3 basic components that we are concerned about right now:

The basic components of an Entry.

So the external ids are the most important. They must be unique, as if the chain already exists it will not work. I recommend adding a few, as the more you add the less likely you will get the same hash as an existing chain. Keep in mind every 1kb cost 1 entry credit, and the first entry in a chain (chain creation) costs 10 entry credits + cost of the entry. So to create the chain it will cost me 11 entry credits.

Step 1: Use as many ‘-e’ flags as you’d like. Each one is an external ID. I recommend having a txt file handy to feed into the command as well, if you do not press “ctrl + d” to send a end of file signal to the command (that is what it is looking for); this becomes the content of the entry.

./factom-cli mkchain -e "Factom Medium Article" -e "Blockchain Education Network" -e "Steven Masley" -e "129707" MyEcWallet < content.txt

It will return your Chain ID. SAVE THIS! If you lose this, then good luck finding your chain again. My Chain ID is: b055d5642db3d44ef2443c1d130867937f78430f26a0d4b97d529c2795f89f49
You must wait for the block to finish, so at most 10 minutes for your entry to be included.
Sidenote: I choose ‘129707’ to ensure the first 4 characters in hex would be “b055” or “Boss” ;)

Done! After few minutes have passed, let’s check it out:

./factom-cli get allentries b055d5642db3d44ef2443c1d130867937f78430f26a0d4b97d529c2795f89f49

Or: http://explorer.factom.org/chain/b055d5642db3d44ef2443c1d130867937f78430f26a0d4b97d529c2795f89f49

So there’s my chain. You can add an entry to it like this:

./factom-cli put -c b055d5642db3d44ef2443c1d130867937f78430f26a0d4b97d529c2795f89f49 -e "The Second entry" -e "This external ids are not needed for the second entry" MyEcWallet < content.txt

For 12 entry credits, I have a chain and entry on Factom. Feel free to add your own entries to my chain, leave a comment there if you can! Also message me on slack if you need help getting access to some entry credits.

That’s all folks

I hope that wasn’t too difficult to follow. Medium formatting is pretty restrictive, and I know I’m being repetitive, but join the BEN slack if you want some personal assistance. I’d be happy to lend a hand.

— Steven Masley
— My Factom Project: Medium Post, DevPost
— Blockchain Education Network