# Concepts

# The State Tree

The entire state of your Lotion application is held in a single state tree; one big JavaScript object. The structure of the data in this state tree is up to you.

Events will happen (eg. users submitting transactions, new blocks being created) which will trigger a set of handlers for that specific event type, and these handlers may mutate the state tree.

Under the hood, your state tree is kept in a Merkle tree by the merk module, so even if your state tree grows very large, your application won't slow down. This also enables efficient queries of arbitrary subtrees of the state.

# Transaction Handlers

Transactions are how users interact with your application. A transaction is a JavaScript object that describes a change to your application state.

A transaction handler is a function which maps a (state, transaction) pair to a deterministic state mutation.

For many small applications, a single handler is all you need. For larger applications, you can build up a stack of transaction handling middleware through multiple calls to app.use(fn)

Before any transaction reaches your application's middleware stack, the validators of your application have already reached consensus about a global ordering for the transactions.

# Block Handlers

Block handlers are functions that can mutate the application state or validator set. They're invoked once per Tendermint block.

# Initializers

Initializers are functions that can set up your initial state. They take (initialState, context) and should mutate your state accordingly. These functions will always be invoked before any transactions are processed.

# Context Object

A context parameter is available for accessing metadata about the the blockchain, such as BFT time, block height, or validator set data from Tendermint.

# Global Chain Identifier (GCI)

In Ethereum, applications exist in a single namespace, which makes interoperability between applications very easy. To call another contract's method, you just need to know its address.

In Lotion, we have a convention of treating the hash of the genesis.json from Tendermint as our application's global identifier. See an example of how we make use of this in the next section.

# Light Clients

Lotion comes with a pure JavaScript light client. The lotion-connect can be used to query for the latest application state and send transactions from Node or the browser.

You can connect to an application using its GCI without knowing the IP of a full node in advance. The client will attempt to reach a full node for the application through the Bittorrent DHT, multicast DNS, and peer exchange servers.

The light client uses a Proxmise-based API, so an efficient query of a state subtree might look like this:

let { connect } = require('lotion')

let { state } = await connect(GCI)

let myBalance = await state.accounts[myAddress].balance

# IBC and Cosmos Interoperability

Lotion is a tool for writing Cosmos zones. Once the design for IBC has been finalized, you will be able to connect Lotion apps with apps written in any other IBC-compatible framework.