Welcome to IOV Weave’s documentation!¶
IOV Weave is a framework to quickly build your custom ABCI application to power a blockchain based on the best-of-class BFT Proof-of-stake Tendermint consensus engine. It provides much commonly used functionality that can quickly be imported in your custom chain, as well as a simple framework for adding the custom functionality unique to your project.
Some of the highlights of Weave include a Merkle-tree backed data store, a highly configurable extension system that also applies to the core logic such as fees and signature validation. Weave also brings powerful customizations initialised from the genesis file. In addition there is a simple ORM which sits on top of a key-value store that also has proveable secondary indexes. There is a flexible permissioning system to use contracts as first-class actors, “No empty blocks” for quick synchronizing on quiet chains, and the ability to introduce “product fees” for transactions that need to charge more than the basic anti-spam fees. We have also added support for “migrations” that can switch on modules, or enable logic updates, via on-chain feature switch transactions.
Existing Modules¶
Module | Description |
---|---|
Cash | Wallets that support fungible tokens and fee deduction functionality |
Sigs | Validate ed25519 signatures |
Multisig | Supports first-class multiple signature contracts, and allow modification of membership |
AtomicSwap | Supports HTLC for cross-chain atomic swaps, according to the IOV Atomic Swap Spec |
Escrow | The arbiter can safely hold tokens, or use with timeouts to release on vesting schedule |
Governance | Hold on-chain elections for text proposals, or directly modify application parameters |
PaymentChannels | Unidirectional payment channels, combine micro-payments with one on-chain settlement |
Distribution | Allows the safe distribution of income among multiple participants using configurations. This can be used to distribute fee income. |
Batch | Used for combining multiple transactions into one atomic operation. A powerful example is in creating single-chain swaps. |
Validators_ | Used in a PoA context to update the validator set using either multisig or the on-chain elections module |
NFT | A generic Non Fungible Token module |
NFT/Username | Example nft used by bnsd. Maps usernames to multiple chain addresses, including reverse lookups |
MessageFee | Validator-subjective minimum fee module, designed as an anti-spam measure. |
Utils | A range of utility functions such as KeyTagger which is designed to enable subscriptions to database. |
In Progress
Light client proofs, custom token issuance and support for IBC (Inter Blockchain Communication) are currently being designed.
Basic Blockchain Terminology¶
If you are new to blockchains (or Tendermint), this is a crash course in just enough theory to follow the rest of the setup. Read all
Immutable Event Log¶
If you are coming from working on typical databases, you can think of the blockchain as an immutable transaction log . If you have worked with Event Sourcing you can consider a block as a set of events that can always be replayed to create a materialized view . Maybe you have a more theoretical background and recognize that a blockchain is a fault tolerant form of state machine replication . Read more
General Purpose Computer¶
Ethereum pioneered the second generation of blockchain, where they realized that we didn’t have to limit ourselves to handling payments, but actually have a general purpose state machine. Read more
Next Generation¶
Since that time, many groups are working on “next generation” solutions that take the learnings of Ethereum and attempt to build a highly scalable and secure blockchain that can run general purpose programs. Read more
Eventual finality¶
All Proof-of-Work systems use eventual finality, where the resource cost of creating a block is extremely high. After many blocks are gossiped, the longest chain of blocks has the most work invested in it, and thus is the true chain. Read more
Immediate finality¶
An alternative approach used to guarantee constency comes out of academic research into Byzantine Fault Tolerance from the 80s and 90s, which “culminated” in PBFT . Read more
Authentication¶
One interesting attribute of blockchains is that there are no trusted nodes, and all transactions are publically visible and can be copied. Read more
Upgrading the state machine¶
Of course, during the lifetime of the blockchain, we will want to update the software and expand functionality. However, the new software must also be able to re-run all transactions since genesis. Read more
UTXO vs Account Model¶
There are two main models used to store the current state. The main model for bitcoin and similar chains is called UTXO, or Unspent transaction output. The account model creates one account per public key address and stores the information there. Read more
Merkle Proofs¶
Merkle trees are like binary trees, but hash the children at each level. This allows us to provide a proof as a chain of hashes. Read more
Running an Existing Application¶
A good way to get familiar with setting up and running an application is to follow the steps in the mycoin sample application. You can run this on your local machine. If you don’t have a modern Go development environment already set up, please follow these instructions.
To connect a node to the BNS testnet on a cloud server, the steps to set up an instance on Digital Ocean are explored in this blog post.
Once you can run the blockchain, you will probably want to connect with it. You can view a sample wallet app for the BNS testnet at https://wallet.hugnet.iov.one Those that are comfortable with Javascript, should check out our IOV Core Library which allows easy access to the blockchain from a browser or node environment.
Configuring your Blockchain¶
When you ran the mycoind
tutorial, you ran the following lines
to configure the blockchain:
tendermint init --home ~/.mycoind
mycoind init CASH bech32:tiov1qrw95py2x7fzjw25euuqlj6dq6t0jahe7rh8wp
This is nice for automatic initialization for dev mode, but for deploying a real network, we need to look under the hood and figure out how to configure it manually.
Tendermint Configuration¶
Tendermint docs provide a brief introduction to the tendermint cli. Here we highlight some of the more important options and explain the interplay between cli flags, environmental variables, and config files, which all provide a way to customize the behavior of the tendermint daemon. Read More
Application State Configuration¶
The application is fed genesis.json
the first time it starts up
via the InitChain
ABCI message. There are three fields that
the application cares about: chain_id
, app_state
,
and validators
. To learn more about these fields
Read More
Setting the Validators¶
Since Tendermint uses a traditional BFT algorithm to reach consensus on blocks, signatures from specified validator keys replace hashes used to mine blocks in typical PoW chains. This also means that the selection of validators is an extremely important part of the blockchain security. Read More
Building your own Application¶
Before we get into the strucutre of the application, there are a few design principles for weave (but also tendermint apps in general) that we must keep in mind.
Determinism¶
The big key to blockchain development is determinism. Two binaries with the same state must ALWAYS produce the same result when passed a given transaction. Read More
Abstract Block Chain Interface (ABCI)¶
To understand this design, you should first understand what an ABCI application is and how that level blockchain abstraction works. ABCI is the interface between the tendermint daemon and the state machine that processes the transactions, something akin to wsgi as the interface between apache/nginx and a django application. Read More
Additional Reading¶
We are in the process of doing a large overhaul on the docs. Until we are finished, please look at the older version of the docs for more complete (if outdated) information