haskoin-store-1.16.6: src/Haskoin/Store.hs
-- |
-- Module : Haskoin.Store
-- Copyright : (c) Haskoin Developers
-- License : MIT
-- Maintainer : jprupp@protonmail.ch
-- Stability : experimental
-- Portability : POSIX
--
-- A block chain indexer for Bitcoin (BTC) and Bitcoin Cash (BCH).
--
-- Haskoin Store connects to the peer-to-peer network with
-- <https://hackage.haskell.org/package/haskoin-node haskoin-node>, downloads
-- blocks and mempool transactions, and indexes the chain in RocksDB. The
-- mempool is one pool in Redis, shared by every store of a fleet, even a
-- fleet of one, and so are the entries of extended public keys
-- (@docs\/one-fleet.md@). The indices answer questions about blocks,
-- transactions, address balances, unspent outputs and extended public keys.
-- A REST API built on them is in "Haskoin.Store.Web".
--
-- = Running a store
--
-- 'withStore' starts everything from a 'StoreConfig': the connection to
-- Redis, the database, the node, the block store that imports data, and the
-- store's membership of its fleet. The 'Store' it returns has a
-- 'DatabaseReader'; query it with the functions of
-- "Haskoin.Store.Database.Query", which take the reader and run in 'IO'.
--
-- @
-- 'withStore' cfg $ \\store ->
-- withSubscription store.pub $ \\events -> do
-- best <- Haskoin.Store.Database.Query.getBestBlock store.db
-- ...
-- @
--
-- = Modules
--
-- * "Haskoin.Store.Data": types of the data returned by the store and the API.
-- * "Haskoin.Store.Common": helpers for paging, ordering and deriving
-- addresses, and 'StoreRead', the queries of a store as a record of
-- functions in 'IO'.
-- * "Haskoin.Store.Database.Reader": opening the RocksDB database.
-- * "Haskoin.Store.Database.Query": queries of the chain in RocksDB, as
-- plain functions, and "Haskoin.Store.Database.Query.Pooled", which lays
-- the fleet's pool over them: what the store answers with.
-- * "Haskoin.Store.Logic": the rules that import and revert blocks, and
-- "Haskoin.Store.Database.Migrate", which brings an older database to the
-- layout of the chain alone. The database has no mempool; see
-- @docs\/one-fleet.md@.
-- * "Haskoin.Store.Fleet": how stores that share a Redis agree on the block
-- that they all answer from, as pure decisions, and
-- "Haskoin.Store.Fleet.Redis", which carries them out.
-- "Haskoin.Store.Fleet.Pool" has the rules of the mempool that they share,
-- and "Haskoin.Store.Fleet.Member" is a store as a member of the fleet.
-- * "Haskoin.Store.Database.Views": the database as it was at each recent
-- block, for a store that answers from the block its fleet agrees on.
-- * "Haskoin.Store.BlockStore": the process that imports blocks and
-- transactions.
-- * "Haskoin.Store.Web": the REST API server.
--
-- = Purpose
--
-- A block chain is easy to append to and hard to query. Bitcoin nodes store
-- blocks, and can answer "give me block N", but not "what is the balance of this
-- address" or "which transactions belong to this wallet". Wallets, block
-- explorers and payment processors all need those answers, quickly, from many
-- clients at once. Haskoin Store maintains the indices that make them cheap, and
-- serves them over HTTP.
--
-- = Design
--
-- * __No full node required.__ The store talks to the peer-to-peer network itself
-- through haskoin-node, so a deployment is one program and a database.
--
-- * __Every import is atomic.__ A block is applied as one RocksDB write. A
-- crash leaves the database at the previous block, never half-way through
-- one, so there is no recovery step.
--
-- * __Indices are designed around reads.__ Keys are laid out so that every API
-- query is a seek and a short scan, newest first; see
-- "Haskoin.Store.Database.Types".
--
-- * __Plain functions in 'IO'.__ Queries take the database reader, or a
-- 'StoreRead' record of them, which the web server builds with the
-- fleet's entries of xpubs in Redis in front of the queries about them. Nothing runs in a stack of
-- monad transformers, except the conduits that merge sorted streams. The
-- web server runs on WAI with a router of its own.
--
-- * __The mempool is a first-class citizen.__ Unconfirmed transactions are indexed
-- like confirmed ones, in the pool in Redis, ordered before them, and kept
-- across restarts of a store, because wallets care about them most.
module Haskoin.Store
( -- * Store
Store (..),
StoreConfig (..),
StoreEvent (..),
withStore,
module Haskoin.Store.BlockStore,
module Haskoin.Store.Web,
module Haskoin.Store.Database.Reader,
module Haskoin.Store.Database.Types,
module Haskoin.Store.Data,
cachePrefix,
-- * Caches of extended public keys
XPubConfig (..),
defaultXPubConfig,
XPubs,
-- * Store Reader
StoreRead (..),
chainRead,
Limits (..),
Start (..),
-- * Useful Functions
getTransaction,
getTransactions,
getDefaultBalance,
getActiveTxData,
blockAtOrBefore,
)
where
import Haskoin.Store.BlockStore
import Haskoin.Store.Common
import Haskoin.Store.Data
import Haskoin.Store.Database.Query.Pooled (chainRead)
import Haskoin.Store.Database.Reader
import Haskoin.Store.Database.Types
import Haskoin.Store.Manager
import Haskoin.Store.Web
import Haskoin.Store.XPub.Service (XPubConfig (..), XPubs, defaultXPubConfig)