How to use your Factoids

Find below the steps necessary to import and send factoids and the relative commands. Before attempting to transact factoids read this guide fully, at least once.

This is early beta software you should use this guide at your own risk, we suggest not to use large amount of factoids in case there may be issues, bugs, or you mistype a command. The Factom Dev Team is working on an easy to use Factoid Wallet App (GUI based), it is some time away and, if unsure how to use the command line, it will be best for you to wait.

For this guide we are using labels to describe factoid addresses factoid1, factoid2. These labels are only known to your local wallet. You can also use the public address (public key) instead of the label, factoid public keys are strings of letters and numbers that start with FA. When you send transactions outside of your local wallet, always use the public key.

Note the difference when sending commands on different platforms:

  • Mac:
    ./factom-cli < rest of the command >

  • Windows:
    factom-cli.exe < rest of the command >

  • Linux:
    factom-cli < rest of the command >

Make sure to change the following commands accordingly.

1. First, you’ll need to have factomd and fctwallet running in other terminal windows. See the guide here to learn how to install the binaries for your OS.

2. Then launch factom-cli in a new terminal window, this is where you will type all the commands. To generate or import an address type:

factom-cli generateaddress fct factoid1

or

factom-cli generateaddress fct factoid1 < Factom Secret Key >

The terminal output will look like:

usefactoids1

The string starting with FA is an actual Factoid Address (public key) where to send and receive Factoids.

"factoid1" is a name/label we have chosen for the new address to make it easy to distinguish between different addresses in your wallet. The first command above, as it is, will create a new address with a balance of zero. “factoid1” will need to have a balance for the purpose of this guide and we’ll use it to send Factoids to another address. You could also import a private key by adding it at the end of the above command as shown in the second option, <> are only placeholders you don’t have to type them. A Factom Secret Key is a string of numbers and letters starting with Fs, keep this safe and do never disclose it to anyone, it’s the equivalent of a private key for a bitcoin address.

You can also use your 12 words Master Passphrase from Koinify to import your Koinify balance to your local factoid wallet.

For example type:

factom-cli importaddress factoid1 "yellow yellow yellow yellow yellow yellow yellow yellow yellow yellow yellow yellow"

The terminal output will look like:

usefactoids2

To make sure your balance is correct copy the resulting Factom Address starting with FA and paste it into http://explorer.factom.org to verify your balance.

In our example we are going to create a new empty address labeled factoid2 which we will use to send factoids from the address labeled factoid1. In your case you would have imported your Koinify balance or a Factoid Secret Key as the address labeled factoid1 and you will use a destination Factoid Address to send factoids to. So we’ll type:

factom-cli generateaddress fct factoid2

The terminal output will look like:

usefactoids3

3. Now it’s time to check your wallet balances, so type:

factom-cli balances

The terminal output will look like:

usefactoids4

4. At this point we are ready to create a new transaction labeled "transaction1" by typing:

factom-cli newtransaction transaction1

The terminal output will look like:

usefactoids5

Replace transaction1 with something more relevant to you, this will be the label for the transaction in all the following steps.

5. Now you need to specify how many factoids you want to send and from which address (input), in this example we want to send 2 factoids, so type:

factom-cli addinput transaction1 factoid1 2

The terminal output will look like:

usefactoids6

Replace factoid1 with either the factoid address starting with FA or your own label given to it when it was created/imported in step 2.

6. Now you need to specify an output, where to send factoids to, so type:

factom-cli addoutput transaction1 factoid2 2

The terminal output will look like:

usefactoids7

Replace factoid2 with either the factoid address starting with FA or your own label given to it when it was created in step 1.

7. Now check how is transaction1 being built and if all looks good by typing:

factom-cli transactions

The terminal output will look like:

usefactoids8

8. Get the transaction fee amount by typing:

factom-cli getfee transaction1

The terminal output will look like:

usefactoids9

9. Add the tx fee to the amount of factoids to send to your input address (factoid1) by typing:

factom-cli addinput transaction1 factoid1 2.012

2 (factoids) + 0.012 (fee) = 2.012 in this case, yours may be different depending on the amount you wish to send. Always double check the total is correct.

The terminal output will look like:

usefactoids10

10. Make sure the fee specified is correct by typing:

factom-cli transactions

The terminal output will look like:

usefactoids11

11. Sign your transaction with:

factom-cli sign transaction1

The terminal output will look like:

usefactoids12

12. Check the signing process is fine with:

factom-cli transactions

The terminal output will look like:

usefactoids13

13. Finally you are ready to submit your transaction with:

factom-cli submit transaction1

The terminal output will look like:

usefactoids14

14. Wait 10 minutes or less depending how far you are from a sixth of an hour, transactions in factom execute at each 10 minutes on the clock so at minute 00, 10, 20, 30… and so on. For instance if it’s 12:00 you have to wait 10 minutes, if it’s 12:28 you have to wait 2 minutes instead.

15. After the right amount of time has passed you can then check your factoids have been transferred to the destination address. If the destination address is not in your local wallet use http://explorer.factom.org to check the balance. Type:

factom-cli balances

The terminal output will look like:

usefactoids15

Recommendations

We strongly recommend to backup your local factoid wallet file every time you import or generate a new address. The wallet file is called "factoid_wallet_bolt.db" and is located in the .factom folder at the following locations:

  • Mac: /Users/YourUsername/.factom/factoid_wallet_bolt.db

  • Windows: /Users/YourUsername/.factom/factoid_wallet_bolt.db

  • Linux: ~/.factom/factoid_wallet_bolt.db

Note that the .factom folder is a hidden folder so perform a Google search for "how to show hidden files and folders on YOUR OS", replace YOUR OS with Mac, Windows or Linux accordingly.

If you want to backup your local wallet file and setup a fresh one you can do so by first quitting factomd and fctwallet, then move your wallet file to a safe location and out of the .factom folder; there should be no wallet file left in there. You can then restart factomd and fctwallet and a fresh new wallet will be generated cointaining no addresses. If you want to restore a previously backup wallet repeat the above, making sure you backup the current wallet, and drag and drop the previous backup in the .factom folder. You can then restart factomd and fctwallet and your previously backup wallet will be used instead. Pay attention when performing backups, each wallet file cointains your Factom Secret Keys (private keys) for each of the addresses cointained within it, if you overwrite a wallet without backup first you may loose your Factoids and Entry Credits.

For a better idea on how transaction fees work, if they are too low when you run submit, the command will fail with a message that tells you how much the fee should be. If you input too much you won’t get an error and you will loose the extra fees.

Do not run fctwallet when you are connected to an unsafe network, like at a cafe, an airport, public wifi hotspot, etc. You could lose factoids. The wallet is unencrypted, and hackers could potentially steal factoids.