Factom is an Open-Source project that provides a way to build applications on the Bitcoin blockchain.
Factom began by providing proof of existence services, but then move on to provide proof of existence of transforms. A list of such entries can be thought of as a Factom Chain. Factom can be used to implement private tokens, smart contracts, smart properties, and more.
Factom leverages the Bitcoin Blockchain, but in a way that minimizes the amount of data actually inserted in the Blockchain. Thus it provides a mechanism for creating Bitcoin 2.0 services for the trading of assets, securities, commodities, or other complex applications without increasing blockchain "pollution".
We are very much at an Alpha level of development. This is the M2 codebase, which is a direct implementation of the Factom Whitepaper.
You need to set up Go environment with golang 1.5 or 1.6. You also need to install the latest version of git, and it doesn't hurt to set up a github account.
###Install the m2 repository
Get the M2 database, with the following command
go get github.com/FactomProject/factomd
You should now be ready to execute factomd
###Testing M2
The test team is working on the master branch, while the developers are working on the m2 branch. But because of shared repositories (some of which have some m2 changes), moving between milestone 1 code, m2s, and m2 is a bit complicated. The all.sh script is your friend. Follow these steps to get M2 setup and running for test:
cd factomd # However or wherever you put it>
./all.sh m2 # This is going to put you into the m2 branch
git checkout master # Gets you back to master
go install # Recompiles factomd with master code
You are now good to go.
Create a ~/.factom/m2 directory
cd to the factomd directory created with the go get.
execute:
cp factomd.conf ~/.factom/m2/
Now you are ready to execute factomd.
go install
factomd
This is the simplist way to execute factomd with the defaults. You can hit "enter" to get the status of the factom nodes running in the simulatory.
factomd can run a simulated network via the commandline. This allows testing of much more complicated networks than would be possible otherwise. The simulator is very extensible, so new features will be added as we go along.
When you run factomd, if no database directory exists in the m2 directory, one is created. All databases are created under the ~/.factom/m2/database directory. These databases are named "bolt" for the main factom node, and "blotSimNNN" where NNN is the node number for Simulation nodes cloned from the main factom node. Inside each of these directories, a network folder is created. LOCAL (for test networks built on your own machine), MAIN for the main network, and TEST for the test network. This allows swapping between networks without concern for corupting the databases.
As M2 runs, journal files are created in the database directory. All messages are journaled for all nodes in the simulator. This gives the ability to "rerun" a message sequence to debug observed issues. When factomd is restarted, all journal files for those nodes are reset.
Below is a discription of how to run journal files.
To get the current list of flags, type the command:
factomd -h
Which will get you something like:
//////////////////////// Copyright 2015 Factom Foundation
//////////////////////// Use of this source code is governed by the MIT
//////////////////////// license that can be found in the LICENSE file.
Go compiler version: go1.5
Using build:
len(Args) 2
Usage of factomd:
-count int
The number of nodes to generate (default 1)
-db string
Override the Database in the Config file and use this Database implementation
-follower
If true, force node to be a follower. Only used when replaying a journal.
-journal string
Rerun a Journal of messages
-net string
The default algorithm to build the network connections (default "tree")
-node int
Node Number the simulator will set as the focus
-test.bench string
regular expression to select benchmarks to run
-test.benchmem
print memory allocations for benchmarks
-test.benchtime duration
approximate run time for each benchmark (default 1s)
-test.blockprofile string
write a goroutine blocking profile to the named file after execution
-test.blockprofilerate int
if >= 0, calls runtime.SetBlockProfileRate() (default 1)
-test.count n
run tests and benchmarks n times (default 1)
-test.coverprofile string
write a coverage profile to the named file after execution
-test.cpu string
comma-separated list of number of CPUs to use for each test
-test.cpuprofile string
write a cpu profile to the named file during execution
-test.memprofile string
write a memory profile to the named file after execution
-test.memprofilerate int
if >=0, sets runtime.MemProfileRate
-test.outputdir string
directory in which to write profiles
-test.parallel int
maximum test parallelism (default 8)
-test.run string
regular expression to select tests and examples to run
-test.short
run smaller test suite to save time
-test.timeout duration
if positive, sets an aggregate time limit for all tests
-test.trace string
write an execution trace to the named file after execution
-test.v
verbose: print additional output
The flags that begin with "test." are supplied by the profiling package installed. The flags that relate to running factomd and the simulator are the following, with a little more explaination. That follows below.
While the simulator is running, you can perform a number of commands to poke at, and examine the state of factomd:
-
aN -- Dump the Admin block at directory block height N. So like a1 or a213. Currently just dumps the JSON.
-
fN -- Dump the Factoid block at directory block height N. So like f5 or f1203. Pretty prints.
-
dN -- Dump the Directory block at directory block height N. d4 or d21230
-
-- gives the state of all nodes in the simulated network.
-
D -- Dumps all the messages in the system to standard out, including the directory blocks and the process lists.
-
s -- Make this server a leader
-
N -- typing a node number shifts focus. You now are talking to said node from the CLI or wallet
Personally I open two consoles. I run factomd redirected to out.txt, and in another console I run tail -f out.txt.
So in one console I run a command like:
factomd -count=10 -net=tree > out.txt
And in another console I run:
tail -f out.txt
Then I type commands in the first console as described above, and see the output in the second. Also messages and errors will show up in the first console (leaving the second console with simple output from factomd).
The command:
factomd -count=10
Will run the simulator with the configuration found in ~/.factom/m2/factom.conf with 10 nodes, named fnode0 to fnode9. fnode0 will be the leader. When you hit enter to get the status, you will see an "L" next to leader nodes.
You can override the database implementation used to run the simulator. The options are "Bolt", "LDB", and "Map". "Bolt" will give you a bolt database, "LDB" will get you a LevelDB database, and "Map" will get you a hashtable based database (i.e. nothing stored to disk"). The most common use of -db is to specify a "Map" database for tests that can be easily rerun without concern for past runs of the tests, or of messing up the database state.
Keep in mind that Map will still overwrite any journals. For example, you can run a 10 node Factom network in memory with the following command:
factoid -count=10 -db=Map
At times it is nice to force factomd to launch a follower rather than a leader (or the other way around). Especially when playing back a journal of messages to investigate why a server got into a particular state. So suppose we have a leader journal leader.log. We could execute that log with this command:
factoid -journal=leader.log -follower=false -db=Map
Or if we had a follower log, follower.log, we could execute it with:
factoid -journal=follower.log -follower=true -db=Map
##3 -journal
Running factomd creates a journal file for every node in the ~/.factom/m2/database/ directory, of the form journalNNN.log where NNN is the node number. So if there is a failure or a desire to rerun the same message stream as a test, this can be done by copying the journalNNN.log files, then running them. For example, suppose we ran a 10 node network and did some testing:
factomd -count=10
<testing done>
Now we can kill factomd, then copy the leader log and a follower log:
cp ~/.factom/m2/database/journal0.log ./leader.log
cp ~/.factom/m2/database/journal3.log ./follower.log
We can then replay these messages in factomd:
factoid -journal=leader.log -follower=false -db=Map
factoid -journal=follower.log -follower=true -db=Map
Keep in mind, after the state has been replayed, the simulator continues to run. So you can easily examine the resulting state, and (in the case of a leader) run more transactions and such. And this is also journaled, so there is an ability to modify and rerun the modified states.
The journal file can also be edited. Only messages (lines that begin with 'MsgHex:' and the following hex) are interpreted. So you can move these lines about, or even copy and paste from other files.
The network is constructed using one of a number of algorithms. tree is the default, and looks like this, where 0 is connected to 1 and 2, 1 is connected to 3 and 4, 2 is connected to 4 and 5, etc.
0
1 2
3 4 5
6 7 8 9
...
circles is a bit hard to map out but it is a series of loops of seven nodes, where each loop is connected to about a 1/3 down from the previous loop, 2/3 down the loop prior to that one (if it exists) and 1/2 the circle 2 prior (if it exists). The goal is to maximize the number of alternate routes to later nodes to test timing of messages through the network.
long is just one long chain of nodes
loops creates a long chain of nodes that have short cuts added here and there.
Running a particular network configuration looks like:
factomd -count=30 -net=tree
factomd -count=30 -net=circles
factomd -count=30 -net=long
factomd -count=30 -net=loops
The simulator always keeps the focus on one node or another. Some commands are node sensitive (printing directory blocks, etc.), and the walletapp and factom-cli talk to the node in focus. This allows you to set the node in focus from the beginning. Mostly a developer thing.
factom -count=30 -node=15 -net=tree
Would start up with node 15 as the focus.
This opens up a TCP port and listens for new connections.
Usage: -p2pAddress="tcp://:8108"
This connects to a remote computer and passes messages and blocks between them.
-peers="tcp://192.168.1.69:8108"
This makes all the simnodes in this process followers. It prefixes the text provided to the Node names (and the generated file names) of all the Factom instances created. So without a prefix, you would get nodes named FNode0, FNode1, etc. With the a_ prefix described below, you would get a_FNode0, a_FNode1, etc.
FNode0 is currently a "magic name", and the node with that name becomes the first default Leader when building Factom up from scratch. (Of course, if you are loading an existing network, it will come up with the last set of leaders). In any event, adding the prefix avoids having FNode0 as a name, and as a result all the nodes will be followers.
-prefix=a_
Multi-computer example:
Computer Leader (ip x.69) factomd -count=2 -p2pAddress="tcp://:8108" -peers="tcp://192.168.1.72:8108"
Computer Follower (ip x.72) factomd -count=5 -p2pAddress="tcp://:8108" -peers="tcp://192.168.1.69:8108" -follower=true -prefix=a_