# haskoin-store-data
Data types and API client of [Haskoin Store](https://github.com/jprupp/haskoin-store),
an indexer for Bitcoin and Bitcoin Cash with a REST API.
Use this package to talk to a Haskoin Store server from Haskell. It has no
database or network node of its own, so it is small to depend on.
## Modules
- `Haskoin.Store.Data`: the types that the server answers with (blocks,
transactions, balances, unspent outputs, extended public keys, health
checks, events, and the Blockchain.info compatible formats), with their
JSON and binary encodings.
- `Haskoin.Store.WebCommon`: the requests of the API, one type per endpoint,
with their paths and parameters.
- `Haskoin.Store.WebClient`: `apiCall`, which sends a request and decodes
the answer, and `apiEvents`, which listens to the events of a server.
## Example
```haskell
import Data.Default (def)
import Haskoin (btc, textToAddr, withContext)
import Haskoin.Store.WebClient
main :: IO ()
main = withContext $ \ctx -> do
let cfg = def {net = btc} -- https://api.haskoin.com/btc/...
Just addr = textToAddr btc "bc1q…"
r <- apiCall ctx cfg (GetAddrBalance addr)
print r
```
The client appends the name of the network to the host, as in the layout of
api.haskoin.com. The binary encoding is used on the wire, as it is smaller and
faster to decode than JSON.
Errors come back as `Left` an `Except`. From version 1.10 they have a binary
encoding too, so a server can answer a binary request with a binary error.
The client reads the `Content-Type` of an error to tell which it got, and so
works with servers of either kind.
## Events
`apiEvents` calls a function with each new block and each transaction that
enters or leaves the mempool, for as long as the function answers `True`.
After a lost connection, `apiEventsAfter` takes up from the last event
heard, so nothing is missed; if the server no longer has that event it
answers `ThingNotFound`, and the client reads what it follows again.
Over the WebSocket at `/events` a client can also choose the transactions
it hears about. `EventCommand` is what it sends: addresses to watch,
extended public keys (one command for each type of address), or a Bloom
filter as in BIP 37. It has a binary encoding and a JSON one, for binary
and text frames. This package has no WebSocket client of its own; send the
encoded command with the one you use:
```haskell
import Haskoin (marshalJSON)
import Haskoin.Store.Data (EventCommand (..))
-- a text frame: {"type":"watch","addresses":["bc1q…"]}
frame = marshalJSON (net, ctx) (EventWatch [addr])
```
Blocks are always told. A connection that has sent no command hears of
every transaction, unless its URL says what to watch, or `quiet=true` for
blocks alone.
The bytes of every type, for someone who writes a client in another
language, are in the "Binary format" section of
[`swagger.yaml`](https://github.com/jprupp/haskoin-store/blob/master/swagger.yaml)
in the haskoin-store repository. In short: integers are big-endian, a list
is its length as 64 bits and then its items, and the events of `/events`
are the one thing sent without a length.
## Building
The package builds with [Stack](https://haskellstack.org) and needs
libsecp256k1 (`libsecp256k1-dev` on Debian and Ubuntu), or Nix with
`stack --nix`:
```sh
stack build
stack test
```
The tests check every type by law: binary encodings round-trip and agree
between Serial, cereal and binary, JSON round-trips, the fast encoders write
the same JSON as `toJSON`, and the wire format of the basic types is pinned.
## Versions
Up to 1.8.1, this package was released from the
[haskoin-store](https://github.com/jprupp/haskoin-store) repository with the
same version number as the server. It now has its own releases; a server
speaks the wire format of the haskoin-store-data version it depends on.
## License
[MIT](LICENSE)