# BitcoinElixir

Bitcoin Cash for Elixir.

- **CashAddr**: encode and decode every address type, including the
  token-aware `z…` and `r…` forms from CashTokens.
- **Watch-only HD keys**: derive receive addresses from an `xpub` (or `tpub`),
  with no private key, so a server can give every invoice its own address.
- **Scripts**: locking scripts and the Electrum scripthash of an address.
- **Electrum / Fulcrum client**: batch requests with failover, and a
  long-lived connection with live address and block notifications.
- **Payment links**: build and parse `bitcoincash:` URIs with exact amounts.

No native dependencies: everything runs on Erlang's `:crypto` and `:ssl`.
Tested against [libauth](https://libauth.org) vectors.

## Install

```elixir
def deps do
  [{:bitcoin_elixir, "~> 0.1"}]
end
```

## Examples

```elixir
alias BitcoinElixir.{CashAddr, HD, Script, PaymentURI, Electrum}

# A fresh receive address for invoice 42, from the shop's account xpub
{:ok, account} = HD.parse("xpub6C…")
address = HD.address(account, [0, 42])
token_address = HD.address(account, [0, 42], tokens: true)

# Addresses
{:ok, %CashAddr{type: :p2pkh, hash: hash}} = CashAddr.decode(address)
{:ok, z} = CashAddr.to_token_aware(address)

# A payment link for 0.0015 BCH (amounts are whole satoshis)
PaymentURI.build(address, amount: 150_000, label: "Order 42")

# Look the address up on Electrum servers
servers = Electrum.default_servers(:mainnet)
{:ok, utxos} =
  Electrum.request("blockchain.scripthash.listunspent", [Script.scripthash!(address)], servers: servers)

# Or watch it live
{:ok, conn} = Electrum.Connection.start_link(servers: servers)
{:ok, _status} = Electrum.Connection.subscribe_scripthash(conn, Script.scripthash!(address))

receive do
  {:electrum, ^conn, {:scripthash, _scripthash, _new_status}} -> :check_the_address_again
end
```

Put `Electrum.Connection` in your supervision tree with a `:name` to share
one connection across your app. Public servers are fine to start with; run
your own [Fulcrum](https://github.com/cculianu/Fulcrum) for production.

## Status

0.1 is watch-only: addresses, derivation, lookups and payment links. It does
not build or sign transactions. Planned next: a supervised payment watcher
(seen, confirmed, double-spend events), CashTokens data in outputs, and
transaction decoding.

## Development

```bash
mix deps.get
mix test
mix docs
```

Test vectors in `test/fixtures` were generated with libauth 3.0.

## Licence

MIT. Built by [Septem Labs](https://septemlabs.com) for Cashlet and Enkaji.
