chrisguida · chrisguida · May 9, 2022 · May 9, 2022 · May 10, 2022 · May 10, 2022
diff --git a/.gitignore b/.gitignore
@@ -1,2 +1,4 @@
 electrs.s9pk
 image.tar
+scripts/embassy.js
+.vscode
diff --git a/Makefile b/Makefile
@@ -1,9 +1,8 @@
-ASSETS := $(shell yq e '.assets.[].src' manifest.yaml)
-ASSET_PATHS := $(addprefix assets/,$(ASSETS))
 VERSION := $(shell yq e ".version" manifest.yaml)
 ELECTRS_SRC := $(shell find ./electrs/src) electrs/Cargo.toml electrs/Cargo.lock
 CONFIGURATOR_SRC := $(shell find ./configurator/src) configurator/Cargo.toml configurator/Cargo.lock
 S9PK_PATH=$(shell find . -name electrs.s9pk -print)
+TS_FILES := $(shell find . -name \*.ts )
 
 .DELETE_ON_ERROR:
 
@@ -12,15 +11,21 @@ all: verify
 verify: electrs.s9pk $(S9PK_PATH)
 	embassy-sdk verify s9pk $(S9PK_PATH)
 
+install: all electrs.s9pk
+	embassy-cli package install electrs.s9pk
+
 clean:
 	rm -f image.tar
 	rm -f electrs.s9pk
 
-electrs.s9pk: manifest.yaml assets/compat/* image.tar instructions.md $(ASSET_PATHS)
+electrs.s9pk: manifest.yaml image.tar instructions.md scripts/embassy.js
 	embassy-sdk pack
 
 image.tar: Dockerfile check*.sh docker_entrypoint.sh configurator/target/aarch64-unknown-linux-musl/release/configurator $(ELECTRS_SRC)
 	DOCKER_CLI_EXPERIMENTAL=enabled docker buildx build --tag start9/electrs/main:$(VERSION) --platform=linux/arm64 -o type=docker,dest=image.tar .
 
 configurator/target/aarch64-unknown-linux-musl/release/configurator: $(CONFIGURATOR_SRC)
 	docker run --rm -it -v ~/.cargo/registry:/root/.cargo/registry -v "$(shell pwd)"/configurator:/home/rust/src start9/rust-musl-cross:aarch64-musl cargo build --release
+
+scripts/embassy.js: $(TS_FILES)
+	deno bundle scripts/embassy.ts scripts/embassy.js
diff --git a/assets/compat/bitcoind.rules.yaml b/assets/compat/bitcoind.rules.yaml
diff --git a/assets/compat/btc-rpc-proxy.rules.yaml b/assets/compat/btc-rpc-proxy.rules.yaml
diff --git a/assets/compat/config_rules.yaml b/assets/compat/config_rules.yaml
diff --git a/assets/compat/config_spec.yaml b/assets/compat/config_spec.yaml
diff --git a/assets/compat/dependencies.yaml b/assets/compat/dependencies.yaml
diff --git a/docs/instructions.md b/docs/instructions.md
@@ -1,3 +1,21 @@
-# Instructions for Hello World
+# Electrum Rust Server (electrs)
 
-Instructions go here.
+`electrs` is an efficient re-implementation of Electrum Server written in Rust. Its main purpose is as an indexer for external wallets that use bitcoind as a backend. There are all sorts of wallets that connect to bitcoind using the Electrum protocol. This Embassy package allows you to run your own electrum server connected to your own Bitcoin Core node, which is the most private, uncensorable, yet fast and easy way to use Bitcoin.
+In order to link a wallet, check out the guides at https://github.com/start9labs/electrs-wrapper/tree/master/docs/wallets.md.
+# Syncing
+
+**WARNING: Make sure you have at least a gigabyte of free RAM before starting Electrs. If you don't, your system will grind to a halt and you will be very unhappy. Pay especially close attention if you're running Mastodon and you have a 4GB system. We recommend that you temporarily stop any services that use lots of RAM, especially Mastodon and Synapse. Keep in mind that Bitcoin Core will also use more RAM than usual during this initial sync.**
+
+When you first start Electrs, it will start building the indexes it needs in order to serve transactions to the wallets that subscribe to it. Electrs will not be usable until after this process completes. On an Embassy, this shouldn't take more than about a day.
+
+Once your electrum server is synced, it will start listening for subscriptions from external wallets.
+
+# Configuration
+
+Electrs on the Embassy requires a fully synced archival Bitcoin Core node as a source for blockchain data. It uses both the RPC interface and the peer interface of `bitcoind` in order to function. This requirement will be automatically enforced by EmbassyOS.
+
+**Bitcoin Core vs Bitcoin Proxy**
+
+If you choose Bitcoin Proxy as your blockchain source, when Electrum makes RPC requests, these will go through Bitcoin Proxy instead of directly to Bitcoin Core. This allows you to control access to your bitcoin node by Electrs and any wallets that are using it.
+
+Note that if you use Proxy as your RPC server, your internal Bitcoin Core node will still be needed as Electrs pulls data from the bitcoin p2p protocol as well, and Proxy does not support serving data via the bitcoin p2p protocol.
diff --git a/docs/integrations/bitbox/assets/bitbox0.png b/docs/integrations/bitbox/assets/bitbox0.png
diff --git a/docs/integrations/bitbox/assets/bitbox1.png b/docs/integrations/bitbox/assets/bitbox1.png
diff --git a/docs/integrations/bitbox/assets/bitbox2.png b/docs/integrations/bitbox/assets/bitbox2.png
diff --git a/docs/integrations/bitbox/assets/bitbox3.png b/docs/integrations/bitbox/assets/bitbox3.png
diff --git a/docs/integrations/bitbox/assets/bitbox4.png b/docs/integrations/bitbox/assets/bitbox4.png
diff --git a/docs/integrations/bitbox/assets/bitbox5.png b/docs/integrations/bitbox/assets/bitbox5.png
diff --git a/docs/integrations/bitbox/assets/bitbox6.png b/docs/integrations/bitbox/assets/bitbox6.png
diff --git a/docs/integrations/bitbox/assets/bitbox7.png b/docs/integrations/bitbox/assets/bitbox7.png
diff --git a/docs/integrations/bitbox/guide.md b/docs/integrations/bitbox/guide.md
@@ -0,0 +1,36 @@
+# BitBox Integration Setup
+
+Note: You will need to be running Tor on your device, find guides to set this up here: https://start9.com/latest/user-manual/connecting/connecting-tor/tor-os/index
+
+1. Open the BitBox App and go to "Settings"
+
+    ![BitBox](./assets/bitbox0.png)
+
+1. Click "Enable Tor Proxy"
+
+    ![Tor](./assets/bitbox1.png)
+
+1. Enable the proxy and enter "127.0.0.1:9050" as the address, then click "Set Proxy Address"
+
+    ![Tor](./assets/bitbox2.png)
+
+1. Back out and click on "Connect your own full node"
+
+    ![Full Node](./assets/bitbox3.png)
+
+    - Note: You may wish to remove the default servers
+
+1. Under "Add a server," add your electrs onion address from your electrs service page (found in your Embassy's electrs service page, under "Interfaces"), followed by :50001 for the port, as shown.  Remove the "http://" prefix, or BitBox will 
+give an error.  Click "Check" to test.
+
+    ![Add Server](./assets/bitbox4.png)
+
+1. If you get the following error, simply restart the app (Tor has not connected) and repeat from Step 4.
+
+    ![Error](./assets/bitbox5.png)
+
+1. You should see the following confirming a successful connection.  Click "Add" to finalize the addition of your node to BitBox.  You will then see it under the list of servers above.
+
+    ![Success](./assets/bitbox6.png)
+
+1. Restart the app and you're ready to use BitBox!!
diff --git a/docs/integrations/bluewallet/guide.md b/docs/integrations/bluewallet/guide.md
@@ -0,0 +1,13 @@
+# BlueWallet Integration Setup
+
+Note: iOS is NOT currently supported as the internal Tor daemon is unstable.  You will need to be running Tor on your device, find guides to set this up here: https://start9.com/latest/user-manual/connecting/connecting-tor/tor-os/index
+
+1. Ensure Orbot is running (in VPN mode) and that you have added BlueWallet to the VPN list, as described in the link above.  BlueWallet has a built in Tor daemon, but it has not been tested to work properly.
+
+1. Open BlueWallet and navigate to the top-right menu -> "Network" -> "Tor Settings," and tap the button at the top for "Disabled."  
+
+1. Go back one page to Network and select "Electrum Server."  
+
+1. Enter your electrs Tor address (found in your Embassy's electrs service page, under "Interfaces"), removing the "http://" prefix.  Then add "50001" for the port and tap "Save."
+
+1. That's it!  You should see a success message.
diff --git a/docs/integrations/electrum/assets/electrum0.png b/docs/integrations/electrum/assets/electrum0.png
diff --git a/docs/integrations/electrum/assets/electrum1.png b/docs/integrations/electrum/assets/electrum1.png
diff --git a/docs/integrations/electrum/assets/electrum2.png b/docs/integrations/electrum/assets/electrum2.png
diff --git a/docs/integrations/electrum/assets/electrum3.png b/docs/integrations/electrum/assets/electrum3.png
diff --git a/docs/integrations/electrum/assets/electrum4.png b/docs/integrations/electrum/assets/electrum4.png
diff --git a/docs/integrations/electrum/guide.md b/docs/integrations/electrum/guide.md
@@ -0,0 +1,21 @@
+# Electrum Integration Setup
+
+Note: You will need to be running Tor on your device, find guides to set this up here: https://start9.com/latest/user-manual/connecting/connecting-tor/tor-os/index
+
+Caution: This will add your Electrum server, but if you want to ONLY connect to your server, you will need to run Electrum in [Single Server Mode](https://electrum.readthedocs.io/en/latest/tor.html) from the CLI.
+
+1. Open Electrum and go to "Tools -> Network," or if you are running for the first time, choose "Select server manually," and click "Next."
+
+    ![Select Server](./assets/electrum0.png)
+
+1. On the following screen, uncheck "Select server automatically," and add in your electrs onion address (found in your Embassy's electrs service page, under "Interfaces").  Remove the "http://" prefix, and add ":50001:t" to indicate the port (50001) and protocol (TCP).  Then click "Next."
+
+    ![Server Setup](./assets/electrum2.png)
+
+1. Select "Use Tor" and "Use Proxy" and enter "127.0.0.1" for the address and 9050 for the port.  Click "Next."
+
+    ![Enable Tor Proxy](./assets/electrum3.png)
+
+1. That's it!  You will be prompted to create a wallet if this is your first time.  You can check your connection by clicking the orb in the bottom right, which should be blue in color.  If your server settings persist, you are connected.
+
+    ![Add Server](./assets/electrum4.png)
diff --git a/docs/integrations/sparrow/assets/sparrow0.png b/docs/integrations/sparrow/assets/sparrow0.png
diff --git a/docs/integrations/sparrow/assets/sparrow1.png b/docs/integrations/sparrow/assets/sparrow1.png
diff --git a/docs/integrations/sparrow/assets/sparrow2.png b/docs/integrations/sparrow/assets/sparrow2.png
diff --git a/docs/integrations/sparrow/assets/sparrow3.png b/docs/integrations/sparrow/assets/sparrow3.png
diff --git a/docs/integrations/sparrow/assets/sparrow4.png b/docs/integrations/sparrow/assets/sparrow4.png
diff --git a/docs/integrations/sparrow/guide.md b/docs/integrations/sparrow/guide.md
@@ -0,0 +1,23 @@
+# Sparrow Integration Setup
+
+Note: You will need to be running Tor on your device, find guides to set this up here: https://start9.com/latest/user-manual/connecting/connecting-tor/tor-os/index
+
+1. Open Sparrow and go to "File -> Preferences -> Server," or if you are running for the first time, proceed through the introduction until the screen below.  Then select "Configure Server."
+
+    ![Configure Server](./assets/sparrow0.png)
+
+1. On the following screen, select "Private Electrum Server."
+
+    ![Electrum Server](./assets/sparrow1.png)
+
+1. Enter your electrs Tor address (found in your Embassy's electrs service page, under "Interfaces"), removing the "http://" prefix.  Enable "Use Proxy" and then enter "127.0.0.1" for the address and "9050" for the port.
+
+    ![Server Setup](./assets/sparrow2.png)
+
+1. Click "Test Connection."
+
+    ![Test](./assets/sparrow3.png)
+
+1. You should see the success message below, then you may return to your wallet, or proceed to create a new one.
+
+    ![Success](./assets/sparrow4.png)
diff --git a/docs/integrations/trezor/assets/trezor0.png b/docs/integrations/trezor/assets/trezor0.png
diff --git a/docs/integrations/trezor/assets/trezor1.png b/docs/integrations/trezor/assets/trezor1.png
diff --git a/docs/integrations/trezor/assets/trezor2.png b/docs/integrations/trezor/assets/trezor2.png
diff --git a/docs/integrations/trezor/assets/trezor3.png b/docs/integrations/trezor/assets/trezor3.png
diff --git a/docs/integrations/trezor/assets/trezor4.png b/docs/integrations/trezor/assets/trezor4.png
diff --git a/docs/integrations/trezor/assets/trezor5.png b/docs/integrations/trezor/assets/trezor5.png
diff --git a/docs/integrations/trezor/guide.md b/docs/integrations/trezor/guide.md
@@ -0,0 +1,29 @@
+# Trezor Integration Setup
+
+Note: You will need to be running Tor on your device, find guides to set this up here: https://start9.com/latest/user-manual/connecting/connecting-tor/tor-os/index
+
+1. Open Trezor and click on the gear icon in the top left to enter the Settings.
+
+    ![Trezor Settings](./assets/trezor0.png "Trezor Settings icon")
+
+1. On the following screen, select the "Crypto"  submenu.
+
+    ![Crypto Settings](./assets/trezor1.png "Trezor Crypto Settings Submenu")
+
+1. On this screen, hover over Bitcoin to show the gear icon, then click on that icon to enter Bitcoin's Settings menu.
+
+    ![Bitcoin Settings](./assets/trezor2.png "Bitocin Settings icon")
+
+1. Under "Backends," click the dropdown menu and select "Custom Electrum Server."
+
+    ![Trezor Backends](./assets/trezor3.png "Trezor Backend Selection")
+
+1. Enter your electrs Tor address (found in your Embassy's electrs service page, under "Interfaces").  Remove the "http://" prefix, then add `:50001:t` at the end, to signify port 50001, TCP connection.  Click "Confirm."
+
+    ![Electrs Address](./assets/trezor4.png "Enter electrs address, port, and tcp setting")
+
+1. If you have not already enabled Tor in the Trezor settings, you will be asked to do so now.  Click "Enable Tor and Confirm," and that's it!  You're now using your Embassy's Bitcoin node with your Trezor Suite!
+
+    ![Enable Tor](./assets/trezor5.png "Enable Tor and Confirm")
+
+    Note: If you are required to enter Tor address and port, use the default: `127.0.0.1:9050`