Factom Quickstart for Developers who Don’t Know or Don’t Care what a Blockchain is — Factomize

Like the title says, this is an explanation of Factom for developers who already have solid programming knowledge and just want a no-buzzword explanation of how to write applications and what is possible. What it is not is a guide to programming or to the underlying Factom protocol itself. If you are interested in the latter, check out some of my other blog posts or the factomprotocol.org website.

Requirements

  • Working knowledge in a programming language
  • Knowing what JSON and JSON-RPC are OR using one of the many Factom APIs

What can I do with Factom?

The Factom protocol is more or less a key-value database that supports three basic functionalities:

  • Add arbitrary data using specific keywords
  • Read data
  • Publishing content
  • Maintaining records
  • Proof of existence

Components

When looking at the official documentation and other APIs, there are going to be several components mentioned:

  • walletd: This is a less important application ("Wallet Daemon"). The wallet is a small database that stores private keys and provides a different JSON-RPC endpoint at :8089 that will let you perform factoid-related actions using only your public key. It's possible to do everything on factomd without a wallet but the wallet needs a factomd endpoint.
  • factom-cli: This is a command line utility to interact with factomd and walletd instead of having to use JSON-RPC.

Running

There are three different networks: the main network, the test network, and your own networks.

Concepts (Basic)

The short version is this:

Two-Token System

There are two types of tokens: Factoids and Entry Credits. If you are building data-driven applications, you’ll spend the majority of your time with Entry Credits.

Addresses

There are two types of addresses, a Factoid Address for Factoids and an EC Address for Entry Credits. Both types consist of a “ private:public " keypair, each a 52 character string. You need a Factoid private key in order to transfer FCT from one address to another or turn them into EC. You need an EC private key in order to write data.

  • Public: FA36Xc9Yjz1gsSinGh6rNiKzhhZnoVdQLkTsUhVYUMeLmVn1aoZS

Transactions

This section could be its own blog, so I will keep it limited to the functionality I typically need as a data-driven developer. To send FCT from one address (that is stored in walletd) to another, use
factom-cli sendfct FA1zT4aFpEvcnPqPCigB3fvGu4Q4mTXY22iiuV69DqE1pNhdF2MC FA28PitepUziaDrLeVAcioNfzHdBc7mvyJJHvag2vyhWm7JR3t8S 1.234.

Exchange

An exchange is a third party site where people can trade Factoids for USD or other currencies. How they manage the association between your account and the factoids depends on their implementation but all the funds are controlled by the exchange until you request them to be transferred to an address only you know the private key of.

Chains & Entries

All data lives in a system of Chains and Entries, with each Entry associated with exactly one Chain, and Entries being traversable from the head of the chain. It’s easier to portray this in a diagram than with words:

Chain Head & Entry Block

The API has calls for “ Chain Head”, “ Entry Block”, and “ Entry “. The chain head takes the chain id and points to the most recent entry block. If new entries are added to the chain, the chain head will change.

Commit & Reveal

Chains and Entries are created in a two-step process. The first step is the Commit which is paying EC to allocate either a Chain or an Entry, and requires the use of an EC Address you control. It does not transmit any actual data, only hashes of the byte data. The second step is Reveal, which is sending the actual byte data. Only after both are sent will the entry be saved. There’s a 24-hour window during which you can send the reveal and the commit doesn’t have to come from the same source as the reveal.

Ack

In order to check the status of a transaction, entry, or chain you can use Ack. This will give you a status update on whether or not your commit/reveal/transaction have been saved yet or whether one exists.

  • NotConfirmed: The data exists in the factomd instance that hosts your API
  • TransactionACK: The data has been sent over the network and the important nodes are planning to save it
  • DBlockConfirmed: The data is saved (this typically takes between 1 and 10 minutes for new data) in a directory block (“DBlock Confirmed”), which means it’s officially saved.

Concepts (Advanced)

The above is enough to work with your own data that you save and retrieve. If you want to build an application that also has to deal with data showing up from other sources, you’ll likely need the directory block.

Directory Block

Similar to Chains and Entries, the entire factom database consists of directory blocks. The “directory block head” points to the most recent directory block and each directory block has a reference to the previous directory block. Inside of dbentries is a list of Entry Blocks that have been updated. There will always be an element for chains c (paying for commits), f (factoid transactions), and a (administrative records).

Height

Every time another directory block is saved, which happens every ten minutes, the height increases by one.

Summary

Putting all of this together, the structure of the data looks like this:

Building Applications

The above describes only the technical aspects of data entry and retrieval but there are a few more very important things.

Chains and Entries are public

You can’t create private chains/entries. You can’t create chains that only you can write to. You can’t stop someone from adding an entry to a chain. Even checking which address paid for an entry can be unreliable (see Commits).

Entries are repeatable

It is possible to submit the same entry twice to the same chain. There is a built-in time-restriction that prevents the same entry inside of an hour (60 minutes), so you never have duplicate entries inside of a single entry block, but in general, you have to be aware that someone else could submit an identical entry to one you submitted (including the identical signature).

Namespace

If you’re planning on having a lot of chains in your system, especially ones not created by you, you can use extids to build namespaces. If the first extid of any new chain is always “MyApp” then you can later poll new data to specifically search for new chains including the keyword. For larger applications, you can use extids as a multi-tiered path.

Examples

Some very basic examples of what a program flow could look like

Logging (Proof of Existence)

You want to prove that your log files are valid by recording their file hash in a chain. The chain is committed and revealed with the following parameters:

ExtId1: MyCompany ExtId2: Log File Hashes
Chain Id: 3d28d16c4831f8be794128bd63b0c0f1fd94898458521d43ebb0b6a24c028c7b ExtId1: 01-01-2019 00:00 ExtId2: filename.log Data: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 <placeholder for a cryptographic signature here that signs the chain id, extid1, extid2, and the file hash>

Reading Unknown Data (Polling)

You just released an application that writes data to Factom and you want to know how many customers are actually using it. Every app has its own chain based on data unknown to you, but you know that the first extid is always “MyApp”.

  1. For every element, call “entry-block” with the element’s “keymr”
  2. Loop through the entry block’s “entrylist” array
  3. For every element, call “entry” for the given “entryhash”
  4. Check the Entry’s first extid to see if it matches “MyApp”
  5. If it does, add the chain to your local database with the current time. If it does not, move on to the next element in 2.

Tic-Tac-Toe (Interactivity)

You want to create a game of Tic-Tac-Toe that you can play against a crowd, where the crowd’s move is determined by voting, with ties going to the first mention. Players have the current and following 3 heights to respond.

  1. You add an entry for your first move (X) with ExtId1 = <gameid>, Extid2 = <signature> and coordinates in the form (x,y) as data. The signature covers both gameid and coordinates.
  2. You wait until the height has increased by 4. Players vote by adding entries with coordinates and randomized nonces in the extids.
  3. Get the chainhead and loop through all the new entries. Discard all entries with invalid (nonexistent, already placed) coordinates and add up the rest. Whichever coordinate has the most entries contains the next “O”. In case of a tie, the one that came first is used
  4. Repeat steps 2–4 until one side has won or it ends in a tie

More

Existing Infrastructure

If you’re going into production, you don’t necessarily have to run your own factomd node. The recommended node is the Factom Open Node, which runs a factomd API endpoint backed up by a cluster. If you are planning on using walletd in combination with either of these, you will need to run that on your own.

API Clients

If you don’t want to code the JSON-RPC calls yourself, you can use one of the existing open source clients or one of the commercial ones. Some are simple API wrappers and some have more functionality.

Existing Projects

There are a lot of different applications all running on the mainnet, some public and some private, but here are a few examples that hopefully cover the whole gamut.

Canonical Ledgers’ Factomize

This is an application running on the Factomize.com forum and will log a signature of every post and edit made. This lets people check whether or not a post has been changed from the original, including a history of changes. Every entry is signed using Factomize’s public key.

Factom Robot

Factom Robot is an application to hash a file and then save that hash to a specific chain as proof of existence, proof of ownership, and timestamping.

Voting

The Voting Protocol is a work in progress to be able to create votes inside Factom. If you look at the specifications, you can see that it’s nothing more than a very complex set of guidelines for the ExtIds and data of chains and entries but correctly entering data (voting) and reading (showing results) is left up to third parties to implement themselves.

Factom Asset Tokens

Factom Asset Tokens (FAT) is a very ambitious project that is essentially a system of tokens running as a second layer on top of factom to create tokens. Explaining FAT is beyond the scope of this article but I wanted to mention it because it works similar to the Tic-Tac-Toe example but on a much, much larger scale, requiring anyone who wants to participate to run fatd, which is an interpreter that has its own clients and APIs. If the restrictions of Factom are unsuitable for your application, you should look into developing it for FAT instead.

Where to go from here

This blog should be enough to get you started but if something goes wrong or isn’t covered, the best place to ask questions would be the channel #developer-discussion in the official Factom discord.

Developer