✨ Lotion ✨

Smooth, easy blockchain apps. Powered by Tendermint consensus.

Lotion is a new way to create blockchain apps in JavaScript, which aims to make writing new blockchains fast and fun. It builds on top of Tendermint using the ABCI protocol. Lotion lets you write secure, scalable applications that can easily interoperate with other blockchains on the Cosmos Network using IBC.

Lotion itself is a tiny framework; its true power comes from the network of small, focused modules built upon it. Adding a fully-featured cryptocurrency to your blockchain, for example, takes only a few lines of code.

Note: the security of this code has not yet been evaluated. If you expect your app to secure real value, please use Cosmos SDK instead.

Installation

Lotion requires node v7.6.0 or higher, and a mac or linux machine.

$ npm install lotion

Usage

app.js:

let lotion = require('lotion')

let app = lotion({
  initialState: {
    count: 0
  }
})

app.use(function(state, tx) {
  if (state.count === tx.nonce) {
    state.count++
  }
})

app.start()

Introduction

Lotion lets you build blockchains. At any moment in time, the whole state of your blockchain is represented by a single JavaScript object called the state.

Users will create transactions: JavaScript objects that tell the application how to mutate the blockchain's state.

Every user who runs your Lotion app will interact with the same blockchain. Anyone can create a transaction, and it will automagically find its way to everyone else running the app and mutate their state. Everyone's state objects will constantly be kept in sync with each other.

A Lotion application is often a single function of signature (state, tx) which mutates your blockchain's state in response to a transaction tx. Both are just objects.

This cosmic wizardry is made possible by a magic piece of software named Tendermint which exists specifically for synchronizing state machines across networks.

Blockchains and Tendermint

The goal of a blockchain is to represent a single state being concurrently edited. In order to avoid conflicts between concurrent edits, it represents the state as a ledger: a series of transformations (transactions) applied to an initial state. The blockchain must allow all connected nodes to agree about which transformations are valid, and their ordering within the ledger.

To accomplish this, a blockchain is composed of three protocols: the network protocol, consensus protocol, and transaction protocol.

The network protocol is how nodes in the network tell each other about new transactions, blocks, and other nodes; usually a p2p gossip network.

The consensus protocol is the set of rules that nodes should follow to determine which particular ordered set of transformations should be in the ledger at a given moment. In Bitcoin, the chain with the highest difficulty seen by a node is treated as authoritatively correct.

The transaction protocol describes what makes transactions valid, and how they should mutate the blockchain's state.

When you're writing a Lotion app, you're only responsible for writing the transaction protocol. Under the hood, Tendermint is handling the consensus and network protocols. When you start your lotion app, a Tendermint node is also started which will handle all of the communication with other nodes running your lotion app.

Modules

name	description
coins	fully-featured cryptocurrency middleware
htlc	hashed timelock contracts on coins
shea	on-chain client code management
merk	merkle AVL trees in javascript

Contributors

Lotion is a cosmic journey for the mind brought to you by:

_Judd 💻 📖 🤔 ⚠️	_{Matt Bell} 💻 🤔 ⚠️ 🔌	_{Jordan Bibla} 🎨	_{Gautier Marin} 📝	_{Jackson Roberts} 💻	_{Mark Price} 📖 ✅ 💡 📹	_{Evan Leong} 🎨
_{Chjango Unchained} 📝 📋	_SaifRehman 💡	_{Lola Dam} 🐛 💻	_{Djenad Razic} 💻	_{Admir Sabanovic} 💻	_{Arne Meeuw} 💬 🤔	_Props.love 💻
_{Peng Zhong} 🎨 💡 🤔

Contributions of any kind welcome!

API

`let app = require('lotion')(opts)`

Create a new Lotion app.

Here are the available options for opts which you can override:

{
  initialState: {},            // initial blockchain state
  keyPath: 'keys.json',        // path to keys.json. generates own keys if not specified.
  genesisPath: 'genesis.json', // path to genesis.json. generates new one if not specified.
  peers: [],                   // array of '<host>:<p2pport>' of initial tendermint nodes to connect to. does automatic peer discovery if not specified.
  logTendermint: false,        // if true, shows all output from the underlying tendermint process
  p2pPort: 26658,              // port to use for tendermint peer connections
  rpcPort: 26657               // port to use for tendermint rpc
}

`app.use(function(state, tx, chainInfo) { ... })`

Transaction handlers will be called for every transaction, in the same order you passed them to app.use().

Transaction handlers must be deterministic: for a given set of state/tx/chainInfo inputs, you must mutate state in the same way.

chainInfo is an object like:

{
  time: 1541415248, // timestamp of the latest block. (unix seconds)
  validators: {
    '<base64-encoded pubkey>' : 20, // voting power distribution for validators. requires understanding tendermint.
    '<other pubkey>': 147 // it's ok if you're not sure what this means, this is usually hidden from you.
  }
}

If you'd like to change how much voting power a validator should have, simply mutate chainInfo.validators[pubKey] at any point!

`app.useBlock(function(state, chainInfo) { ... })`

Add middleware to be called once per block, even if there haven't been any transactions. Should mutate state, see above to read more about chainInfo.

Most things that you'd use a block handler for can and should be done as transactions.

`app.start()`

Starts your app.

Global Chain Identifiers and Light Clients

Lotion apps each have a unique global chain identifier (GCI). You can light client verify any running Lotion app from any computer in the world as long as you know its GCI.

let { connect } = require('lotion')
let GCI = '6c94c1f9d653cf7e124b3ec57ded2589223a96416921199bbf3ef3ca610ffceb'

let { state, send } = await connect(GCI)

let count = await state.count
console.log(count) // 0

let result = await send({ nonce: 0 })
console.log(result) // { height: 42, ok: true }

count = await state.count
console.log(count) // 1

Under the hood, the GCI is used to discover and torrent the app's genesis.json.

It's also used as the rendezvous point with peers on the bittorrent dht and through multicast DNS to find a full node light client verify.

You can get the GCI of an app being run by a full node like this:

let app = require('lotion')({ initialState: { count: 0 } })

let { GCI } = await app.start()
console.log(GCI) // '6c94c1f9d653cf7e124b3ec57ded2589223a96416921199bbf3ef3ca610ffceb'

License

MIT

keppel / lotion

readme