Graphene – An Open Source Blockchain

Graphene – An Open Source Blockchain

By Phil Mesnier, OCI Partner & Principal Engineer

MARCH 2017


By now, you have likely heard words like "bitcoin" and "blockchain," perhaps even "Ethereum," and wondered what they all mean.

Do they refer to something useful, and if so, how would you go about using it?

This article is intended to put meaning behind these words and others, by highlighting one instance of the technology behind the concepts.

Blockchain, like many other technologies supported and used by OCI, is middleware. It is not an end in itself; rather it is the means to an end. 

Blockchains are useful in the way databases are, storing data and allowing its manipulation, but with a twist. Data is stored in a blockchain as an immutable record of transactions. Integrity of the chain is maintained through the use of an algorithm, which verifiably links each new block to the history of blocks that precede it back to the origin of the chain.

Graphene, an Open Source, mostly C++, blockchain implementation was originally developed as the foundation of Bitshares, a cryptocurrency exchange marketplace.

The Graphene source is available in numerous variations, as it has been forked and adapted many times. The original release is managed by an organization known as Cryptonomex.

Graphene is interesting because it is Open Source, but also because it was developed in a modular fashion, making it adaptable to many different uses.

In addition to Bitshares, Graphene serves as the blockchain foundation for, a news aggregation site similar in concept to and, a gaming site. is another example of a service built on the Graphene blockchain. FollowMyVote uses Graphene to facilitate secure, yet private, internet-based municipal voting.

There are many other users of Graphene beyond this sample list.

Enterprise Blockchain Solutions

Prepare for the transformational impact of blockchain, from fully traceable supply chains to immutable identity management, with our portfolio of fully connected, smart blockchain solutions.

Get Started Now


For those of you who have not heard of this technology, the internet is full of descriptions. I suggest you search "what is blockchain" on, where you will find several good examples.

Here's a quick "Blockchain 101" and some basic terms.

A blockchain is a linked list of records of transactions involving data state changes over time. The linkage of these blocks of records is done using cryptographic algorithms, which merge together information about the transactions recorded in the current block, as well as information about the block that precedes it.

Here is a diagram that illustrates the concept.

Figure 1: A very loose illustration of blocks on a chain

Some Terms Defined

A container (or simply a descriptor) of data relevant to this blockchain. The data is typically a collection of transactions that describe changes to the data. These could be records of transfer of assets from one owner to another, or could be the record of some personal information being updated. Depending on the required performance characteristics, blocks may contain many or a few transactions. Blocks also contain a header which holds certain meta-information about the block, including a reference to the preceding block.
A value that is computed by some algorithm, which uniquely identifies the input data without revealing the contents of that data. Hash values are used to ensure the veracity of data on the blockchain. The block headers contain the previous block’s hash, which enables the integrity of the entire chain to be quickly verified.
Genesis block
This is the first block in the chain. It is created when a blockchain is first deployed, serving as the anchor to which all other blocks link.
A record of a change to the data set. Transactions are typically based on rules defined by the blockchain. These rules comprise contracts between parties.
Smart contract
A contract, which may include its own behavior in order to trigger events that independently create transactions.
A host in a network that is capable of adding blocks to the chain. The way nodes are able to do this varies based on the needs of the chain.
Distributed Ledger
A recording of transactions shared across the nodes. A blockchain to which many nodes may contribute blocks is also known as a distributed ledger.
A strategy method used by nodes in a distributed ledger and defined by the blockchain to determine the correctness of the chain. The most common consensus strategies are “proof of work,” “proof of stake,” and “delegated proof of stake.” Graphene employs the delegated proof of stake strategy.
Proof of work (PoW)
A consensus strategy that relies on a computationally difficult challenge to solve in order to find the hash of a new block. Although the original block hashing algorithm is difficult to solve, the discovered solution is easy for others to verify, allowing the other participating nodes to quickly agree that the new block is correct.
Proof of stake (PoS)
A consensus strategy that relies on nodes which hold collateral to participate in contributing blocks to the chain. With proof of stake, blocks may be added to the chain more quickly.
Delegated proof of stake (DPoS)
A variation of proof of stake in which the responsibility of the creating blocks is delegated to third party nodes, known as "witnesses."
A node in a DPoS blockchain that performs the task of creating new blocks.

Blockchain Glossary of Terms

Learn to discuss blockchain like a pro with our glossary of blockchain terms.

Explore Blockchain Glossary

Uses of Blockchain

As more and more people learn about blockchain, the pool of use-case examples continues to grow.

The earliest uses focused on the transfer of virtual currency. That asset transfer capability can extend to the real world for supply-chain management, evidence custody, or any other situation where irrefutable proof of ownership is required.

An additional class of use cases focuses on the management of the rules that enforce transactions. These rules can be combined to define contracts, and these contracts may include coding of actions which make the contract itself a participant. These are often referred to as smart contracts.

We will take a closer look at smart contracts on Graphene in a subsequent SETT article

Consensus is a major contributor to the strength of a blockchain, particularly if the participants are unknown to each other and, therefore, lack trust. The blockchain addresses that issue by defining the means by which the blocks contributed to the chain by any node is validated by other nodes.

However, it might not be desirable to put proprietary or otherwise sensitive data on a publicly accessible blockchain. In those cases, the blockchain may be made private. A private blockchain could use a simpler consensus mechanism, which in turn, makes it easier to deploy on a small number of nodes, perhaps only one.

A Peek Under the Hood

The Graphene blockchain is not a monolithic application. It is composed of a variety of libraries and executables to provide deployable nodes.

Figure 2 provides an illustration of the various source code packages distributed with Graphene.

In addition to the packages shown below, Graphene also has a dependency on standard C++ 11 and Boost packages, while also providing a substantial test suite.

Figure 2: A package dependency view of Graphene components

Obtaining and Running Graphene

Graphene is Open Source software available on GitHub. The root repository may be found at the Cryptonomex site.

There are three projects to be cloned: graphene, graphene-ui, and fc.

OCI's GitHub page includes forks of graphene and graphene-ui, which serve as our research base repository. You may clone OCI's copy of graphene by visiting and

Comprehensive build and deploy instructions for both kits are included in their respective files.

Graphene ships with three executables: the witness_node,cli_wallet, and genesis_util. Once built, you can try running a witness node.

Note this example shows how to run the witness node with command line options.
dhcp19:graphene phil$ cd programs/witness_node
dhcp19:witness_node phil$ ./witness_node --rpc-endpoint --enable-stale-production -w '"1.6.0"'
2560491ms th_a       main.cpp:126                  main                 ] Writing new config file at /tao_builds/phil/projects/blockchain/phil/graphene/programs/witness_node/witness_node_data_dir/config.ini
2560511ms th_a       witness.cpp:89                plugin_initialize    ] witness plugin:  plugin_initialize() begin
2560511ms th_a       witness.cpp:99                plugin_initialize    ] key_id_to_wif_pair: ["GPH6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV","5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3"] 
2560511ms th_a       witness.cpp:117               plugin_initialize    ] witness plugin:  plugin_initialize() end
2560512ms th_a       application.cpp:357           startup              ] Replaying blockchain due to version upgrade
2560512ms th_a       application.cpp:254           operator()           ] Initializing database...
2560518ms th_a       db_management.cpp:51          reindex              ] reindexing blockchain
2560518ms th_a       db_management.cpp:104         wipe                 ] Wiping database
2560549ms th_a       object_database.cpp:87        wipe                 ] Wiping object database...
2560549ms th_a       object_database.cpp:89        wipe                 ] Done wiping object databse.
2560549ms th_a       object_database.cpp:94        open                 ] Opening object database from /tao_builds/phil/projects/blockchain/phil/graphene/programs/witness_node/witness_node_data_dir/blockchain ...
2560549ms th_a       object_database.cpp:100       open                 ] Done opening object database.
2560560ms th_a       db_debug.cpp:85               debug_dump           ] total_balances[asset_id_type()].value: 0 core_asset_data.current_supply.value: 1000000000000000 
2560560ms th_a       db_management.cpp:58          reindex              ] !no last block
2560560ms th_a       db_management.cpp:59          reindex              ] last_block:  
2560562ms th_a       thread.cpp:95                 thread               ] name:ntp tid:123145365336064
2560562ms th_a       thread.cpp:95                 thread               ] name:p2p tid:123145366409216
2560566ms th_a       application.cpp:143           reset_p2p_node       ] Configured p2p node to listen on
2560568ms th_a       application.cpp:195           reset_websocket_serv ] Configured websocket rpc to listen on
2560568ms th_a       witness.cpp:122               plugin_startup       ] witness plugin:  plugin_startup() begin
2560568ms th_a       witness.cpp:129               plugin_startup       ] Launching block production for 1 witnesses.
*                              *
*   ------- NEW CHAIN ------   *
*   - Welcome to Graphene! -   *
*   ------------------------   *
*                              *
Your genesis seems to have an old timestamp
Please consider using the --genesis-timestamp option to give your genesis a recent timestamp
2560568ms th_a       witness.cpp:140               plugin_startup       ] witness plugin:  plugin_startup() end
2560568ms th_a       main.cpp:179                  main                 ] Started witness node on a chain with 0 blocks.
2560568ms th_a       main.cpp:180                  main                 ] Chain ID is 0e435e3d20d8efa4e47fae56707a460e35c034aa2b0848e760e51beb13b3db04

After you get the node running, you can connect to the node using the cli_wallet. In a second terminal window, run the command line wallet application.

dhcp19:graphene phil$ cd program/cli_wallet
dhcp19:cli_wallet phil$ ./cli_wallet 
Logging RPC to file: logs/rpc/rpc.log
2838642ms th_a       main.cpp:120                  main                 ] key_to_wif( committee_private_key ): 5KCBDTcyDqzsqehcb52tW5nU6pXife6V2rX9Yf7c3saYSzbDZ5W 
2838649ms th_a       main.cpp:124                  main                 ] nathan_pub_key: GPH6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV 
2838650ms th_a       main.cpp:125                  main                 ] key_to_wif( nathan_private_key ): 5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3 
Starting a new wallet with chain ID 0e435e3d20d8efa4e47fae56707a460e35c034aa2b0848e760e51beb13b3db04 (from egenesis)
2838655ms th_a       main.cpp:172                  main                 ] wdata.ws_server: ws://localhost:8090 
2838726ms th_a       main.cpp:177                  main                 ] wdata.ws_user:  wdata.ws_password:  
Please use the set_password method to initialize a new wallet before continuing
2838792ms th_a       thread.cpp:95                 thread               ] name:getline tid:123145506545664
new >>> 

At this point, you can use the help command to explore how to use the wallet interface.

Programming with Graphene

The basic API for Graphene is based on remote procedure calls. The specific functions available depend on the terms of the contracts, defined by a particular blockchain instance.

A common authentication module is accessed first through the login API. After authenticating, the client application is able to gather other remote object references and make calls to them.

The FC library is used to manage the transport details, allowing the nodes to accept a variety of transport protocols.

As currently delivered, the witness_node application is configured to accept HTTP formatted requests. From a C++ application, the Graphene apps library and FC library work together to provide a simple programming model for such access.

Here is an example, taken from the cli_wallet application, showing how to connect to the node server, log in, and make additional calls.

  1. fc::http::websocket_client client;
  2. idump((wdata.ws_server));
  3. auto con = client.connect( wdata.ws_server );
  4. auto apic = std::make_shared<fc::rpc::websocket_api_connection>(*con);
  6. auto remote_api = apic->get_remote_api< login_api >(1);
  7. edump((wdata.ws_user)(wdata.ws_password) );
  8. // TODO: Error message here
  9. FC_ASSERT( remote_api->login( wdata.ws_user, wdata.ws_password ) );
  11. auto wapiptr = std::make_shared<wallet_api>( wdata, remote_api );
  12. wapiptr->set_wallet_filename( wallet_file.generic_string() );
  13. wapiptr->load_wallet_file();
  15. fc::api<wallet_api> wapi(wapiptr);
  17. auto wallet_cli = std::make_shared<fc::rpc::cli>();
  18. for( auto& name_formatter : wapiptr->get_result_formatters() )
  19. wallet_cli->format_result( name_formatter.first, name_formatter.second );

Without getting too deep, what is shown here is that wdata is some collection of initialization information collected from the command line, config files, etc. This is then used to create a client connection, log in (asserting that it was successful), creating an instance of the wallet API that communicates through the authenticated reference to make further calls.

Look for future SETT articles to explore the Graphene API in greater depth.

Looking Ahead

Blockchain has many applications, from financial services, to identity security, to supply-chain management, and beyond. Supporting these numerous uses are many different implementations.

I believe Graphene is a particularly significant blockchain framework because of its modularity. By separating the inter-nodal communication support from the logic, it is possible to replace layer the logic components of Graphene on another transport mechanism, such as OCI’s OpenDDS. This Open Source product enables OpenDDS-based, low footprint applications (such as IIoT devices) to add blockchain related functionality with the least overhead increase possible.

I anticipate that we will be seeing even more adaptation of blockchain technology in other domains, such as Grails, as well. Over time, I expect to see OCI become a leader at tailoring blockchain solutions, whether based on Graphene or some other foundation.

References & Further Reading

Software Engineering Tech Trends (SETT) is a regular publication featuring emerging trends in software engineering.