README

FILES

Your wallet and your private keys are stored in app internal storage:

/data/data/de.schildbach.wallet/files/wallet-protobuf (MODE_PRIVATE)
	Wallet for Mainnet

/data/data/de.schildbach.wallet/files/wallet-protobuf-testnet (MODE_WORLD_READABLE | MODE_WORLD_WRITEABLE)
	Wallet for Testnet

The wallet file format is not compatible to wallet.dat (Satoshi client). Rather, it uses a custom protobuf format
which should be compatible between clients using bitcoinj.

Certain actions cause automatic rolling backups of your private keys to app-private storage:

/data/data/de.schildbach.wallet.digitalcoin/files/key-backup-base58 (MODE_PRIVATE)
	Automatic backups of private keys for Mainnet


Private keys can be manually backed up to and restored from external storage:


/sdcard/Download/digitalcoin-wallet-keys-<yyyy-MM-dd>
	Manual backups of private keys for Mainnet

/sdcard/Download/digitalcoin-wallet-keys-testnet-<yyyy-MM-dd>
	Manual backups of private keys for Testnet


The manual backup files are encrypted using your chosen password. You can use OpenSSL to decrypt:

openssl enc -d -aes-256-cbc -a -in <filename>


DEBUGGING

Wallet file for Testnet can be pulled from an (even un-rooted) device using

	adb pull /data/data/de.schildbach.wallet/files/wallet-protobuf-testnet

Log messages can be viewed by

	adb logcat

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


BUILDING THE DEVELOPMENT VERSION

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

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

You'll need git, a Java SDK 6 (or later) and Maven 3.0.4 for this. I'll assume Ubuntu Linux for
the package installs.

	# first time only
	sudo apt-get install git maven openjdk-6-jdk

If you want to use Maven 3.1.0 or later, you need edit pom.xml to use android-maven-plugin version
3.8.2 or later.

Get the Android SDK Tools from

	http://developer.android.com/sdk/

and unpack it to your workspace directory. Switch to that Android SDK directory, and use

	# first time only
	tools/android update sdk --no-ui --force --filter platform,platform-tools

to download the necessary API level.

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

	# first time only
	git clone -b master https://github.com/HashEngineering/digitalcoin-wallet.git bitcoin-wallet

	# each time
	cd bitcoin-wallet
	git pull
	mvn clean install -Dandroid.sdk.path=<path to your android sdk>

To upload the app to your Android device, use

	# first time only
	sudo apt-get install android-tools-adb

	# each time
	adb install wallet/target/wallet-*-test.apk


BUILDING THE PRODUCTIVE VERSION

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.

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

	# each time
	cd bitcoin-wallet
	git fetch origin
	git checkout origin/prod
	mvn clean install -Prelease -Dandroid.sdk.path=<path to your android sdk>


SETTING UP FOR DEVELOPMENT

Make sure you've got Eclipse 3.7 (Indigo) with ADT 20 installed.

Use Git to check out the project and an Android library dependency to your workspace:

	# clone Bitcoin Wallet project
	git clone -b master https://github.com/HashEngineering/digitalcoin-wallet.git bitcoin-wallet

	# clone ActionBarSherlock library project
	git clone https://github.com/JakeWharton/ActionBarSherlock.git action-bar-sherlock
	cd action-bar-sherlock
	git checkout 4.1.0

Use the maven-eclipse-plugin to create Eclipse project files:

	cd bitcoin-wallet
	mvn eclipse:eclipse

Optional: In the generated .classpath, remove the org.eclipse.jdt.launching.JRE_CONTAINER
classpath entry. It does not belong there, but cannot be excluded from being generated currently.

In Eclipse, use File -> Import -> General -> Existing Project into Workspace to import project.

If you see loads of "should be tagged with @Override" errors, set Project -> Properties ->
Java Compiler -> Errors/Warnings -> Annotations -> Missing @Override annotation to 'Warning'


NFC (Near field communication)

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:

- We have successfully tested this NFC tag writer:
  https://play.google.com/store/apps/details?id=com.nxp.nfc.tagwriter
  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,
  then share with messaging or email. You can also construct the URI manually. Example for Mainnet:
  bitcoin:1G2Y2jP5YFZ5RGk2PXaeWwbeA5y1ZtFhoL

- 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.


EXCHANGE RATES

Bitcoin Wallet reads this feed from "bitcoin charts" for getting exchange rates:

	http://bitcoincharts.com/t/weighted_prices.json

The feed is described on this page (see Weighted Prices):

	http://bitcoincharts.com/about/markets-api/

I chose this feed because it is not dependent on a single exchange. However, you should keep in
mind it's always a 24h average (falling back to 7d or even 30d if no trade occurred for a long
time).

If Bitcoincharts is not available, the feed from "Blockchain" is fetched instead:

	https://blockchain.info/ticker

The feed is described here:

	https://blockchain.info/api/exchange_rates_api


BITCOINJ

Bitcoin Wallet uses bitcoinj for Bitcoin specific logic:

http://code.google.com/p/bitcoinj/