\n \n\nLotion 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](https://tendermint.com) using the [ABCI](https://github.com/tendermint/abci) protocol. Lotion lets you write secure, scalable applications that can easily interoperate with other blockchains on the [Cosmos Network](https://cosmos.network/) using [IBC](https://github.com/cosmos/ics).\n\nLotion 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.](https://github.com/mappum/coins)\n\nNote: the security of this code has not yet been evaluated. If you expect your app to secure real value, please use [Cosmos SDK](https://github.com/cosmos/cosmos-sdk) instead.\n\n## Installation\n\nLotion requires **node v7.6.0** or higher, and a mac or linux machine.\n\n```\n$ npm install lotion\n```\n\n## Usage\n\n`app.js`:\n\n```js\nlet lotion = require('lotion')\n\nlet app = lotion({\n initialState: {\n count: 0\n }\n})\n\napp.use(function(state, tx) {\n if (state.count === tx.nonce) {\n state.count++\n }\n})\n\napp.start()\n```\n\n## Introduction\n\nLotion 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`.\n\nUsers will create `transactions`: JavaScript objects that tell the application how to mutate the blockchain's `state`.\n\nEvery 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.\n\nA 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.\n\nThis cosmic wizardry is made possible by a magic piece of software named [Tendermint](https://github.com/tendermint/tendermint) which exists specifically for synchronizing state machines across networks.\n\n### Blockchains and Tendermint\n\nThe 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.\n\nTo accomplish this, a blockchain is composed of three protocols: the **network** protocol, **consensus** protocol, and **transaction** protocol.\n\nThe **network** protocol is how nodes in the network tell each other about new transactions, blocks, and other nodes; usually a p2p gossip network.\n\nThe **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.\n\nThe **transaction** protocol describes what makes transactions valid, and how they should mutate the blockchain's state.\n\n**_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.\n\n## Modules\n\n| name | description |\n| ---------------------------------------------------- | ---------------------------------------- |\n| [coins](https://github.com/mappum/coins) | fully-featured cryptocurrency middleware |\n| [htlc](https://github.com/mappum/htlc) | hashed timelock contracts on coins |\n| [shea](https://github.com/keppel/shea) | on-chain client code management |\n| [merk](https://github.com/mappum/merk) | merkle AVL trees in javascript |\n\n## Contributors\n\nLotion is a cosmic journey for the mind brought to you by:\n\n\n\n| [ Judd](https://twitter.com/juddkeppel) [💻](https://github.com/keppel/lotion/commits?author=keppel \"Code\") [📖](https://github.com/keppel/lotion/commits?author=keppel \"Documentation\") [🤔](#ideas-keppel \"Ideas, Planning, & Feedback\") [⚠️](https://github.com/keppel/lotion/commits?author=keppel \"Tests\") | [ Matt Bell](https://github.com/mappum) [💻](https://github.com/keppel/lotion/commits?author=mappum \"Code\") [🤔](#ideas-mappum \"Ideas, Planning, & Feedback\") [⚠️](https://github.com/keppel/lotion/commits?author=mappum \"Tests\") [🔌](#plugin-mappum \"Plugin/utility libraries\") | [ Jordan Bibla](http://www.jordanbibla.com) [🎨](#design-jolesbi \"Design\") | [ Gautier Marin](https://github.com/gamarin2) [📝](#blog-gamarin2 \"Blogposts\") | [ Jackson Roberts](https://github.com/Jaxkr) [💻](https://github.com/keppel/lotion/commits?author=Jaxkr \"Code\") | [ Mark Price](http://spentak.com) [📖](https://github.com/keppel/lotion/commits?author=spentak \"Documentation\") [✅](#tutorial-spentak \"Tutorials\") [💡](#example-spentak \"Examples\") [📹](#video-spentak \"Videos\") | [ Evan Leong](http://www.fountapp.com) [🎨](#design-evanmayo \"Design\") |\n| :---: | :---: | :---: | :---: | :---: | :---: | :---: |\n| [ Chjango Unchained](https://cosmos.network) [📝](#blog-Chjango \"Blogposts\") [📋](#eventOrganizing-Chjango \"Event Organizing\") | [ SaifRehman](https://github.com/SaifRehman) [💡](#example-SaifRehman \"Examples\") | [ Lola Dam](https://github.com/rllola) [🐛](https://github.com/keppel/lotion/issues?q=author%3Arllola \"Bug reports\") [💻](https://github.com/keppel/lotion/commits?author=rllola \"Code\") | [ Djenad Razic](http://www.machinezdesign.com) [💻](https://github.com/keppel/lotion/commits?author=MisterDr \"Code\") | [ Admir Sabanovic](http://dev.ba) [💻](https://github.com/keppel/lotion/commits?author=criticalbh \"Code\") | [ Arne Meeuw](http://meeuw.me) [💬](#question-ameeuw \"Answering Questions\") [🤔](#ideas-ameeuw \"Ideas, Planning, & Feedback\") | [ Props.love](https://www.props.love) [💻](https://github.com/keppel/lotion/commits?author=propslove \"Code\") |\n| [ Peng Zhong](http://cosmos.network) [🎨](#design-nylira \"Design\") [💡](#example-nylira \"Examples\") [🤔](#ideas-nylira \"Ideas, Planning, & Feedback\") |\n\n\n\nContributions of any kind welcome!\n\n## API\n\n### `let app = require('lotion')(opts)`\n\nCreate a new Lotion app.\n\nHere are the available options for `opts` which you can override:\n\n```js\n{\n initialState: {}, // initial blockchain state\n keyPath: 'keys.json', // path to keys.json. generates own keys if not specified.\n genesisPath: 'genesis.json', // path to genesis.json. generates new one if not specified.\n peers: [], // array of ':' of initial tendermint nodes to connect to. does automatic peer discovery if not specified.\n logTendermint: false, // if true, shows all output from the underlying tendermint process\n p2pPort: 26658, // port to use for tendermint peer connections\n rpcPort: 26657 // port to use for tendermint rpc\n}\n```\n\n### `app.use(function(state, tx, chainInfo) { ... })`\n\nRegister a transaction handler. Given a `state` and `tx` object, mutate `state` accordingly.\n\nTransaction handlers will be called for every transaction, in the same order you passed them to `app.use()`.\n\nTransaction handlers must be deterministic: for a given set of `state`/`tx`/`chainInfo` inputs, you **must** mutate `state` in the same way.\n\n`chainInfo` is an object like:\n\n```js\n{\n time: 1541415248, // timestamp of the latest block. (unix seconds)\n validators: {\n '' : 20, // voting power distribution for validators. requires understanding tendermint.\n '': 147 // it's ok if you're not sure what this means, this is usually hidden from you.\n }\n}\n```\n\nIf you'd like to change how much voting power a validator should have, simply mutate chainInfo.validators[pubKey] at any point!\n\n### `app.useBlock(function(state, chainInfo) { ... })`\n\nAdd 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`.\n\nMost things that you'd use a block handler for can and should be done as `transactions`.\n\n### `app.start()`\n\nStarts your app.\n\n## Global Chain Identifiers and Light Clients\n\nLotion 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.\n\n```js\nlet { connect } = require('lotion')\nlet GCI = '6c94c1f9d653cf7e124b3ec57ded2589223a96416921199bbf3ef3ca610ffceb'\n\nlet { state, send } = await connect(GCI)\n\nlet count = await state.count\nconsole.log(count) // 0\n\nlet result = await send({ nonce: 0 })\nconsole.log(result) // { height: 42, ok: true }\n\ncount = await state.count\nconsole.log(count) // 1\n```\n\nUnder the hood, the GCI is used to discover and torrent the app's genesis.json.\n\nIt'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.\n\nYou can get the GCI of an app being run by a full node like this:\n\n```js\nlet app = require('lotion')({ initialState: { count: 0 } })\n\nlet { GCI } = await app.start()\nconsole.log(GCI) // '6c94c1f9d653cf7e124b3ec57ded2589223a96416921199bbf3ef3ca610ffceb'\n```\n\n## Links\n\n- go read more at [https://lotionjs.com](https://lotionjs.com)!\n\n## License\n\nMIT\n","maintainers":[{"email":"kepzorz@gmail.com","name":"kep"},{"email":"mappum@gmail.com","name":"mappum"}],"time":{"modified":"2022-05-08T11:07:09.844Z","created":"2017-08-12T18:34:11.338Z","0.0.0":"2017-08-12T18:34:11.338Z","0.0.1":"2017-08-16T16:27:42.869Z","0.0.2":"2017-08-16T21:46:52.953Z","0.0.3":"2017-08-21T21:56:00.727Z","0.0.4":"2017-08-22T22:49:31.558Z","0.0.6":"2017-08-31T22:26:40.369Z","0.0.7":"2017-09-11T17:02:16.589Z","0.0.8":"2017-09-12T19:32:28.268Z","0.0.9":"2017-09-25T15:51:44.768Z","0.0.10":"2017-09-27T06:46:48.017Z","0.0.11":"2017-10-17T00:58:06.278Z","0.0.12":"2017-10-18T23:28:10.629Z","0.0.13":"2017-10-25T02:49:09.390Z","0.0.14":"2017-11-04T00:38:00.437Z","0.0.15":"2017-11-08T22:39:37.422Z","0.1.1":"2017-11-13T21:16:37.750Z","0.1.2":"2017-11-17T22:34:14.102Z","0.1.4":"2017-11-20T09:45:57.952Z","0.1.5":"2017-11-29T17:00:35.731Z","0.1.6":"2017-12-07T01:04:37.100Z","0.1.7":"2017-12-11T19:46:53.003Z","0.1.8":"2017-12-15T21:01:26.928Z","0.1.9":"2018-01-19T19:20:44.389Z","0.1.10":"2018-01-20T01:20:48.027Z","0.1.11":"2018-01-20T19:05:35.230Z","0.1.12":"2018-02-11T22:24:23.613Z","0.1.13":"2018-02-14T22:36:20.817Z","0.1.14":"2018-03-01T23:21:34.631Z","0.1.15":"2018-03-05T07:21:01.064Z","0.1.16":"2018-03-17T19:28:50.876Z","0.1.17":"2018-03-24T03:22:15.680Z","0.1.18":"2018-04-08T20:51:18.420Z","0.1.19":"2018-07-04T19:15:17.893Z","0.2.0":"2018-09-08T00:37:30.621Z","0.2.1":"2018-09-26T12:15:57.426Z","0.2.2":"2018-10-01T10:59:38.669Z","0.2.3":"2018-10-10T10:32:09.833Z","0.3.0":"2018-12-20T01:33:43.686Z","0.4.0":"2019-01-03T02:21:35.201Z","0.4.1":"2019-01-03T05:37:37.249Z","0.4.2":"2019-01-03T07:37:37.823Z","0.4.3":"2019-01-05T03:52:16.255Z","0.4.4":"2019-01-15T06:02:44.843Z","0.4.5":"2019-01-15T06:59:24.520Z","0.4.6":"2019-02-01T03:55:07.049Z","0.4.7":"2019-02-01T04:15:41.813Z","0.4.8":"2019-02-01T05:25:31.092Z","0.4.9":"2019-02-13T06:13:11.994Z","0.4.10":"2019-03-03T05:12:42.542Z","0.4.11":"2019-04-30T01:46:49.423Z","0.4.12":"2019-05-04T02:00:52.266Z","0.4.13":"2019-05-04T02:30:14.571Z","0.4.14":"2019-05-04T02:45:12.331Z","0.4.15":"2019-05-04T02:52:46.352Z","0.4.16":"2019-05-04T04:58:06.353Z","0.4.17":"2019-05-07T03:52:25.913Z","0.4.18":"2019-05-07T04:28:32.178Z","0.4.19":"2019-05-07T04:52:47.088Z","0.4.20":"2019-05-07T05:09:58.620Z","0.4.21":"2019-05-08T22:15:17.457Z","0.4.22":"2019-05-08T23:08:50.237Z","0.4.23":"2019-05-09T00:48:35.678Z","0.4.24":"2019-05-11T00:22:05.684Z","0.4.25":"2019-05-11T00:54:08.703Z","0.4.26":"2019-05-13T22:00:15.714Z","0.4.27":"2020-06-01T19:45:57.368Z"},"keywords":[],"author":{"name":"Judd Keppel","email":"kepzorz@gmail.com"},"license":"ISC","readmeFilename":"readme.md","homepage":"https://github.com/nomic-io/lotion#readme","repository":{"type":"git","url":"git+https://github.com/nomic-io/lotion.git"},"bugs":{"url":"https://github.com/nomic-io/lotion/issues"}}
![\"Lotion\"](\"https://user-images.githubusercontent.com/1269291/36411921-a4eadaf6-15cc-11e8-9614-b316de38d534.png\")
\n ![\"Travis](\"https://img.shields.io/travis/nomic-io/lotion/master.svg\"\n)
\n \n \n ![\"NPM](\"https://img.shields.io/npm/dm/lotion.svg\"\n)
\n \n \n ![\"NPM](\"https://img.shields.io/npm/v/lotion.svg\"\n)
\n \n \n ![\"chat](\"https://img.shields.io/badge/chat-on%20slack-7A5979.svg\"){kind=icon}
\n \n \n ![\"test](\"https://img.shields.io/codecov/c/github/keppel/lotion/develop.svg\")
\n \n \n![](\"https://avatars2.githubusercontent.com/u/1269291?v=4\")
![](\"https://avatars2.githubusercontent.com/u/398285?v=4\")
![](\"https://avatars1.githubusercontent.com/u/6021933?v=4\")
![](\"https://avatars0.githubusercontent.com/u/18440102?v=4\")
![](\"https://avatars3.githubusercontent.com/u/1147244?v=4\")
![](\"https://avatars3.githubusercontent.com/u/758121?v=4\")
![](\"https://avatars2.githubusercontent.com/u/14792822?v=4\")
![](\"https://avatars0.githubusercontent.com/u/8525850?v=4\")
![](\"https://avatars3.githubusercontent.com/u/18755233?v=4\")
![](\"https://avatars3.githubusercontent.com/u/1772945?v=4\")
![](\"https://avatars1.githubusercontent.com/u/2449579?v=4\")
![](\"https://avatars3.githubusercontent.com/u/5900925?v=4\")
![](\"https://avatars1.githubusercontent.com/u/5405348?v=4\")
![](\"https://avatars1.githubusercontent.com/u/36277340?v=4\")
![](\"https://avatars0.githubusercontent.com/u/172531?v=4\")