README.md 6.74 KB
Newer Older
1 2 3
Technical details
=================

4
### FILES
Andreas Schildbach's avatar
Andreas Schildbach committed
5

6 7
Your wallet contains your private keys and various transaction related metadata. It is stored in app-private
storage:
8

9 10
    Mainnet: /data/data/de.schildbach.wallet/files/wallet-protobuf
    Testnet: /data/data/de.schildbach.wallet_test/files/wallet-protobuf-testnet
Andreas Schildbach's avatar
Andreas Schildbach committed
11

12
The wallet file format is not compatible to wallet.dat (Satoshi client). Rather, it uses a custom protobuf format
Andreas Schildbach's avatar
Andreas Schildbach committed
13
which should be compatible between clients using bitcoinj.
14

15
Certain actions cause automatic rolling backups of your wallet to app-private storage:
16

17 18
    Mainnet: /data/data/de.schildbach.wallet/files/key-backup-protobuf
    Testnet: /data/data/de.schildbach.wallet_test/files/key-backup-protobuf-testnet
19

20
Your wallet can be manually backed up to and restored from a share of the storage access framework (likely Google Drive):
21

22 23
    Mainnet: bitcoin-wallet-backup-<yyyy-MM-dd>
    Testnet: bitcoin-wallet-backup-testnet-<yyyy-MM-dd>
24

25
If you want to recover coins from manual backups and for whatever reason you cannot use the app
26
itself to restore from the backup, see the separate [README.recover.md](README.recover.md) guide.
27

28 29 30 31 32 33
The current fee rate for each of the fee categories (economic, normal, priority) is cached in
app-private storage:

    Mainnet: /data/data/de.schildbach.wallet/files/fees.txt
    Testnet: /data/data/de.schildbach.wallet_test/files/fees-testnet.txt

Andreas Schildbach's avatar
Andreas Schildbach committed
34

35
### DEBUGGING
Andreas Schildbach's avatar
Andreas Schildbach committed
36

37
Wallet file for Testnet can be pulled from an (even un-rooted) device using:
Andreas Schildbach's avatar
Andreas Schildbach committed
38

39
    adb pull /data/data/de.schildbach.wallet_test/files/wallet-protobuf-testnet
Andreas Schildbach's avatar
Andreas Schildbach committed
40

41
Log messages can be viewed by:
Andreas Schildbach's avatar
Andreas Schildbach committed
42

43
    adb logcat
Andreas Schildbach's avatar
Andreas Schildbach committed
44

45
The app can send extensive debug information. Use **Options > Settings > Report Issue** and follow the dialog.
46 47
In the generated e-mail, replace the support address with yours.

Andreas Schildbach's avatar
Andreas Schildbach committed
48

49
### BUILDING THE DEVELOPMENT VERSION
50

51
It's important to know that the development version uses Testnet, is debuggable and the wallet file
52
is world readable/writeable. The goal is to be able to debug easily.
53 54 55

You can probably skip some steps, especially if you built Android apps before.

56
You'll need git, a Java6 SDK (or later) and Gradle 3.4 (or later) for this. I'll assume Ubuntu 18.04 LTS (Bionic Beaver)
57
for the package installs, which comes with slightly more recent versions.
58

59
    # first time only
60
    sudo apt install git gradle openjdk-8-jdk
61

62
Create a directory for the Android SDK (e.g. `android-sdk`) and point the `ANDROID_HOME` variable to it.
63

64 65
Download the [Android SDK Tools](https://developer.android.com/studio/index.html#command-tools)
and unpack it to `$ANDROID_HOME/`.
66

67
Install the NDK:
68

69 70
    # first time only
    $ANDROID_HOME/bin/tools/sdkmanager ndk-bundle
71

72
Finally, you can build Bitcoin Wallet and sign it with your development key. Again in your workspace,
73
use:
74

75 76
    # first time only
    git clone -b master https://github.com/bitcoin-wallet/bitcoin-wallet.git bitcoin-wallet
77

78 79 80
    # each time
    cd bitcoin-wallet
    git pull
81
    gradle clean test build
82

83
To install the app on your Android device, use:
84

85
    # each time
86
    gradle installDebug
87

88
If installation fails, make sure "Developer options" and "USB debugging" are enabled on your Android device, and an ADB
89 90
connection is established.

91

92
### BUILDING THE PRODUCTIVE VERSION
93 94 95 96 97

At this point I'd like to remind that you continue on your own risk. According to the license,
there is basically no warranty and liability. It's your responsibility to audit the source code
for security issues and build, install and run the application in a secure way.

98
The production version uses Mainnet, is built non-debuggable, space-optimized with ProGuard and the
99
wallet file is protected against access from non-root users. In the code repository, it lives in a
100
separate 'prod' branch that gets rebased against master with each released version.
101

102 103 104 105
    # each time
    cd bitcoin-wallet
    git fetch origin
    git checkout origin/prod
106
    gradle clean test build
107 108


109
### SETTING UP FOR DEVELOPMENT
110

111
You should be able to import the project into Android Studio, as it uses Gradle for building.
112 113


114
### TRANSLATIONS
115

116
The source language is English. Translations for all languages except German [happen on Transifex](https://www.transifex.com/bitcoin-wallet/bitcoin-wallet/).
117

118
The English resources are pushed to Transifex. Changes are pulled and committed to the git
119
repository from time to time. It can be done by manually downloading the files, but using the `tx`
120 121
command line client is more convenient:

122 123
    # first time only
    sudo apt install transifex-client
124 125 126 127 128

If strings resources are added or changed, the source language files need to be pushed to
Transifex. This step will probably only be executed by the maintainer of the project, as special
permission is needed:

129 130
    # push source files to Transifex
    tx push -s
131 132 133

As soon as a translation is ready, it can be pulled:

134 135
    # pull translation from Transifex
    tx pull -f -l <language code>
136 137 138 139 140

Note that after pulling, any bugs introduced by either translators or Transifex itself need to be
corrected manually.


141
### NFC (Near field communication)
Andreas Schildbach's avatar
Andreas Schildbach committed
142 143 144 145 146 147 148 149 150

Bitcoin Wallet supports reading Bitcoin requests via NFC, either from a passive NFC tag or from
another NFC capable Android device that is requesting coins.

For this to work, just enable NFC in your phone and hold your phone to the tag or device (with
the "Request coins" dialog open). The "Send coins" dialog will open with fields populated.

Instructions for preparing an NFC tag with your address:

151
- We have successfully tested [this NFC tag writer](https://play.google.com/store/apps/details?id=com.nxp.nfc.tagwriter).
Andreas Schildbach's avatar
Andreas Schildbach committed
152 153 154 155 156
  Other writers should work as well, let us know if you succeed.

- Some tags have less than 50 bytes capacity, those won't work. 1 KB tags recommended.

- The tag needs to contain a Bitcoin URI. You can construct one with the "Request coins" dialog,
157
  then share with messaging or email. You can also construct the URI manually. Mainnet example:
158
  `bitcoin:1G2Y2jP5YFZ5RGk2PXaeWwbeA5y1ZtFhoL`
Andreas Schildbach's avatar
Andreas Schildbach committed
159 160 161 162 163

- The type of the message needs to be URI or URL (not Text).

- If you put your tag at a public place, don't forget to enable write protect. Otherwise, someone
  could overwrite the tag with his own Bitcoin address.
164 165


166
### BITCOINJ
167

168
Bitcoin Wallet uses [bitcoinj](https://bitcoinj.github.io/) for Bitcoin specific logic.
169 170


171
### EXCHANGE RATES
172

173
Bitcoin Wallet reads this feed from "BitcoinAverage" for getting exchange rates:
174

175
    https://apiv2.bitcoinaverage.com/indices/global/ticker/short?crypto=BTC
176

177 178
We chose this feed because it is not dependent on a single exchange. This feature can be disabled
with the compile-time flag
179 180

    Constants.ENABLE_EXCHANGE_RATES
181

182

183
### SWEEPING WALLETS
184

185
When sweeping wallets, Bitcoin Wallet uses a set of Electrum servers to query for unspent transaction
186
outputs (UTXOs). This feature can be disabled with the compile-time flag:
187 188

    Constants.ENABLE_SWEEP_WALLET