From c8bd7c0d17c0d4fb23d1bea01d11f158e15551dd Mon Sep 17 00:00:00 2001 From: timlucmiptev Date: Tue, 10 Nov 2020 14:49:03 +0200 Subject: [PATCH] start arch doc --- ARCH.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 ARCH.md diff --git a/ARCH.md b/ARCH.md new file mode 100644 index 0000000000..750a49ead0 --- /dev/null +++ b/ARCH.md @@ -0,0 +1,35 @@ +# 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, simple state machine primitives. + +System summary: +- `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 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 is a primitive for tracking wallet state, including available addresses an existing/watched addresses. + +It can take address inputs from any local source. This allows the possibility of creating import programs for pre-existing wallet data, or large amounts of wallet data. + +## btc-wallet-hook +I don't like the name "hook" here, but can't think of anything better atm. It's closer to a data source/manager on top of the wallet, potentially just one of many. + + +## 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. + + +## Possible Improvements +- Multiple Providers +- Gossip network for both pulling and pushing address updates +