shrub/ARCH.md

# Urbit Bitcoin Architecture

## Intro
This architecture is, by Urbit standards, awkward. The awkwardness arises mainly from the asymmetry of full nodes: only a few nodes are providers/full nodes, and they have to keep remote clients updated as to the state of the blockchain. The system also requires providers to run a node side-by-side with their Urbit, although this can mostly be abstracted away as HTTP calls out.

My goal in designing this was to isolate the architecture's awkwardness as much as possible to specific chokepoints, and to keep the non-provider portions as clean state machine primitives.

System parts:
- `btc-wallet-store`: holds wallets and watches their addresses
  * tracks whether a wallet has been scanned
  * generates receiving addresses and change addresses
  * can take address state input from any agent on its own ship
- `btc-wallet-hook`: requests BTC state from provider and forwards it
  * subscribes to wallet-store for any address requests.
  * pokes wallet-store with new address info
- `btc-provider`: 
- helper BTC libraries for address and transaction generation.

## btc-wallet-store
Intentionally very limited in function. It's a primitive for tracking wallet state, including available addresses an existing/watched addresses.

Addresses are put in a watchlist if they have UTXOs *or* have been previously used. "Used" means either existing in transactions already, or having been generated by the store's `gen-address` gate, which generates and watches a new address, and increments the next "free" address.

You add a wallet to the store by adding that wallet's xpub. The store scans that xpub's change and non-change addresses in batches, by sending the address batches to its subscribers and taking pokes back with info for each address.  The scan is done when store sees `max-gap` consecutive unused addresses.

Any source on the ship can poke the store with address info. This allows the possibility of creating import programs for pre-existing wallet data, or large amounts of wallet data. Currently, the only program that interacts with it is `btc-wallet-hook`.

Incoming data:
- requested address info
- unsolicited address updates (checked against watch list)
- requests to generate and watch new addresses

Outgoing data:
- requests for address info
- newly generated/watched addresses

## btc-wallet-hook
I don't like the name "hook" here, but can't think of anything better atm. It's closer to a non-wallet-state manager on top of the wallet-store; potentially just one of many.

It interfaces with hte 

Outgoing data:

Incoming data:

Error conditions:
Disconnected provider: when it receives a message that this is the case, it stops sending outgoing address info requests until the provider says it's back up. Once we receive a connected message, all pending requests are retried.

## btc-provider
Layers on top of both BTC and ElectRS *TODO explain why the latter*

Incoming data:

Outgoing data:

Error conditions:

## Resource Usage

### Provider
- machine: requires hard drive and processing to run a BTC full node and ElectRS indexer.
- network: sends out *all* addresses in each new block to *all* clients

### Wallet
- machine: processes all addresses for each block to see whether they are being watched.
- network: receives all addresses for each block

## Needed Extensions
- Invoice generator that asks for addresses on behalf of ships and tracks whether they've made payments. `wallet-hook` could probably be renamed to `wallet-manager` and extended for this purpose.
- `btc-provider` should push out address state in each block
- `btc-wallet-store` should watch the next ~20 addresses in each wallet account, so that it can detect BTC sent to the wallet if the wallet is also managed/generates addresses in an outside-Urbit program.

## Possible Improvements/Changes
- Do away with `btc-wallet-hook` altogether in its current form, and instead make `btc-provider` both a server (as it is now) and also a client. Pros: conceptually clean; less between-agent data. Cons: complicates the otherwise simple provider codebase.
- Multiple Providers
- Gossip network for both pulling and pushing address updates to lower network usage on the providers.