README.md 9.07 KB
Newer Older
Thibaut Sardan's avatar
Thibaut Sardan committed
1
![Parity Signer](https://wiki.parity.io/images/logo-parity-signer.jpg)
Marek Kotewicz's avatar
Marek Kotewicz committed
2

3
4
5
[<img src="./res/github-badge.png" width="250"/>](https://github.com/paritytech/parity-signer/releases/)
[<img src="./res/google-play-badge.png" width="250"/>](https://play.google.com/store/apps/details?id=io.parity.signer)
[<img src="./res/app-store-badge.png" width="250"/>](https://itunes.apple.com/us/app/parity-signer/id1218174838)
Thibaut Sardan's avatar
Thibaut Sardan committed
6
7
8

# Parity Signer - Turn your smartphone into a hardware wallet

Thibaut Sardan's avatar
Thibaut Sardan committed
9
Parity Signer is a mobile application that allows any smartphone to act as an air-gapped crypto wallet. This is also known as "cold storage".
Thibaut Sardan's avatar
Thibaut Sardan committed
10

Thibaut Sardan's avatar
Thibaut Sardan committed
11
You can create Kusama and Ethereum accounts, sign messages/transactions, and transfer funds to and from these accounts without any sort of connectivity enabled on the device.
Thibaut Sardan's avatar
Thibaut Sardan committed
12

Thibaut Sardan's avatar
Thibaut Sardan committed
13
You must turn off or even physically remove the smartphone's Wifi, Mobile Network, and Bluetooth to ensure that the mobile phone containing these accounts will not be exposed to any online threat.
Thibaut Sardan's avatar
Thibaut Sardan committed
14

Thibaut Sardan's avatar
Thibaut Sardan committed
15
16
**Disabling the mobile phone's networking abilities is a requirement for the app to be used as intended.**

Thibaut Sardan's avatar
Thibaut Sardan committed
17
Have a look at the tutorial on our wiki to learn how to use [Parity Signer together with Polkadot-js app](https://wiki.parity.io/Parity-Signer-Mobile-App-Apps-Kusama-tutorial) for Kusama,  or [MyCrypto app](https://wiki.parity.io/Parity-Signer-Mobile-App-MyCrypto-tutorial) and [Parity Fether](https://wiki.parity.io/Parity-Signer-Mobile-App-Fether-tutorial) for Ethereum.
Thibaut Sardan's avatar
Thibaut Sardan committed
18

Thibaut Sardan's avatar
Thibaut Sardan committed
19
Any data transfer from or to the app happens using QR code. By doing so, the most sensitive piece of information, the private keys, will never leave the phone. The Parity Signer mobile app can be used to store any Kusama or Ethereum account, this includes KSM, ETH, ETC as well as Ether from various testnets (Kovan, Ropsten...).
Thibaut Sardan's avatar
Thibaut Sardan committed
20

Thibaut Sardan's avatar
Thibaut Sardan committed
21
## Device security
Thibaut Sardan's avatar
Thibaut Sardan committed
22

Thibaut Sardan's avatar
Thibaut Sardan committed
23
Parity Signer was built to be used offline. The mobile device used to run the app will hold valuable information that needs to be kept securely stored. It is therefore advised to:
Thibaut Sardan's avatar
Thibaut Sardan committed
24
- Use a dedicated mobile device (not your everyday phone).
Thibaut Sardan's avatar
Thibaut Sardan committed
25
26
27
- Make a factory reset.
- Enable full-disk encryption on the device, with a reasonable password (might not be on by default, for example for older Android devices).
- Do not use any kind of biometrics such as fingerprint or face recognition for device decryption/unlocking, as those may be less secure than regular passwords.
Thibaut Sardan's avatar
Thibaut Sardan committed
28
- Once the app has been installed, enable airplane mode and make sure to switch off Wifi, Bluetooth or any connection ability of the device.
Thibaut Sardan's avatar
Thibaut Sardan committed
29
30
31
32
- Only charge the phone on a power outlet that is never connected to the internet. Only charge the phone with the manufacturer's charging adapter. Do not charge the phone on public USB chargers.

## Screenshots

Thibaut Sardan's avatar
Thibaut Sardan committed
33
![Parity Signer Screenshots](docs/screenshots.png)
Thibaut Sardan's avatar
Thibaut Sardan committed
34
35

## Build it
36
37
### Requirements

38
- `node.js` ( `>=10`)
Marek Kotewicz's avatar
Marek Kotewicz committed
39
- `yarn` (tested on `1.6.0`)
40
41
42
- `rustup` (tested on `rustup 1.16.0`)
- `rustc` (tested on `rustc 1.32.0 (9fda7c223 2019-01-16)`)
- `cargo` (tested on `cargo 1.32.0 (8610973aa 2019-01-02)`)
43
- `cocoapods` (`$ sudo gem install cocoapods`)
44
- `android_ndk` (tested on `r19`)
45
46
- `Android Studio` (only for Android, tested on `Version 3.3`)
- `Xcode` (only for iOS, tested on `Version 9.4.1 (9F2000)`)
47
- `$NDK_HOME` envarionment variable set to ndk home directory (eg. `/usr/local/opt/android-ndk`)
Marek Kotewicz's avatar
Marek Kotewicz committed
48
- `$JAVA_HOME` envarionment variable set to java home directory (eg. `/Library/Java/JavaVirtualMachines/jdk1.8.0_60.jdk/Contents/Home`)
49
50
- `$ANDROID_HOME` environment variable set to Android SDK directory (eg. `/home/your_username/Android/Sdk`)*.

51
\* It's recommended to install **Android Studio** and use that to install the necessary build tools and SDKs for the Android version you want to test on. It's also the best way to test in the emulator. **DO NOT INSTALL NDK VIA ANDROID STUDIO** as that will install the latest version. Make sure to get `r19` instead.
52

Thibaut Sardan's avatar
Thibaut Sardan committed
53
### Setup
54
55
56
57
58

- macOS

    ```
    ./setup_macos.sh
59
60
61

    echo "ndk.dir=$NDK_HOME" > android/local.properties
    echo "sdk.dir=$ANDROID_HOME" >> android/local.properties
62
63
64
65
66
67
    ```

- linux

    ```
    ./setup_linux.sh
68
69
70

    echo "ndk.dir=$NDK_HOME" > android/local.properties
    echo "sdk.dir=$ANDROID_HOME" >> android/local.properties
71
    ```
Marek Kotewicz's avatar
Marek Kotewicz committed
72

Thibaut Sardan's avatar
Thibaut Sardan committed
73
### Usage
Marek Kotewicz's avatar
Marek Kotewicz committed
74

75
76
77
78
79
80
81
82
- Install Dependencies

    ```
    yarn
    cd ios && pod install && cd ..
    ```   

- Start React Native server with increased heap to prevent out of memory error
83
84
85
86
87
88
89

    ```
    yarn start
    ```

Then:
 
90
91
92
- iOS

    ```
93
    yarn run ios
94
95
96
97
98
    ```

- Android

    ```
99
    yarn run android
100
101
    ```

Marek Kotewicz's avatar
Marek Kotewicz committed
102

Thibaut Sardan's avatar
Thibaut Sardan committed
103
### Test Parity Signer
104

Thibaut Sardan's avatar
Thibaut Sardan committed
105
For a super quick test and to avoid the hurdle of creating an account, sending funds to it and finally create a transaction as described in the [tutorial using Parity Fether](https://wiki.parity.io/Parity-Signer-Mobile-App-Fether-tutorial) or the [tutorial using MyCrypto](https://wiki.parity.io/Parity-Signer-Mobile-App-MyCrypto-tutorial), you can use a pre-funded account on Kovan Network and the following workflow. To get access to this account, you need to:
Thibaut Sardan's avatar
Thibaut Sardan committed
106
107
108
109
110

- Recover an account
- Select `Kovan` network and choose a name
- Use the recovery phrase: `this is sparta` you'll get the account address: `006E27B6A72E1f34C626762F3C4761547Aff1421`
- Validate and accept the warning message
Thibaut Sardan's avatar
Thibaut Sardan committed
111
112
- Chose a pin code
- Scan this QR code to sign a transaction sending some Kovan Eth to the same account.
Marek Kotewicz's avatar
Marek Kotewicz committed
113

Thibaut Sardan's avatar
Thibaut Sardan committed
114
![qr code parity signer](docs/tx_qr.png)
Marek Kotewicz's avatar
Marek Kotewicz committed
115

Thibaut Sardan's avatar
Thibaut Sardan committed
116
Corresponding data:
Marek Kotewicz's avatar
Marek Kotewicz committed
117
118
119

```json
{
Thibaut Sardan's avatar
Thibaut Sardan committed
120
121
122
123
124
    "action": "signTransaction",
    "data": {
        "account": "006e27b6a72e1f34c626762f3c4761547aff1421",
        "rlp": "ea1584ee6b280082520894006e27b6a72e1f34c626762f3c4761547aff1421872386f26fc10000802a8080"
    }
Marek Kotewicz's avatar
Marek Kotewicz committed
125
126
}
```
127

128
129
#### Unit Test

130
Run `yarn unit` for all the units test.
131
132
133
134

If debugging is needed:

1. Insert `debugger;` in the code where you think it fails.
135
2. Run `yarn unit:debug`
136
137
138
139
3. Open a new tab in Chrome and go to `chrome://inspect`
4. Click the `inspect` button of target under `Remote Target`
5. Back to the terminal, choose one of the node watch commands to run the tests again.

140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
#### Integration Test

Parity Signer is integrated with [Detox](https://github.com/wix/Detox) E2E testing. Detox has very detailed [documentation](https://github.com/wix/Detox/blob/master/docs/README.md).

First make sure `detox-cli` is installed as global dependency with

```
yarn global add detox-cli
```

##### Complete Test

1. run react native server with `yarn start`

2. run `yarn e2e:ios` or `yarn e2e:android`.

##### Develop and Test
Details please refer to Detox official guide [here](https://github.com/wix/Detox/blob/master/docs/Guide.DevelopingWhileWritingTests.md)

Once you have run `yarn ios` you do not need to build it, just run:
```shell
yarn test-e2e:ios
```
This command will open another simulator with the pre-defined configurations.

Re-run tests without re-installing the app
```
yarn test-e2e:ios --reuse
```

If you want to use another specific emulator/simulator than those defined in the configuration, add `--device-name` flag (on Android API version is needed), for example:
```
yarn test-e2e:ios --device-name iPhone X
yarn test-e2e:android --device-name Pixel_2_API_28
```

On Android please replace `ios` with `android`, currently Detox's Android 0.60.x support is in progress, if there is an error, try to build it again with `yarn build-e2e:android`

178
179
### Troubleshooting

Edi Sinovcic's avatar
Edi Sinovcic committed
180
#### `No dimension set for key window` on Android < 5.0
181
182
183
184
185
186
187
188
189
190
191

This error should be accompanied with `error: closed` in terminal when deploying the debug version of the signer on a device that runs Android older than 5.0. It happens because the Android API does not support the reverse proxy that would allow the phone to communicate with the debug server on your computer.

A suitable workaround is to run both devices on the same WiFi and use your local WiFi IP address. Check your WiFi settings for your local IP address (eg. `192.168.1.42`), then, while having the app open on the phone (either on error page or blank screen) run a command in terminal:

```
adb shell input keyevent 82
```

(You can find `adb` binary in your local Android SDK folder under `platform-tools`, eg. `/home/your_username/Android/Sdk/platform-tools`)

Thibaut Sardan's avatar
Thibaut Sardan committed
192
This should open a menu on the device. In that menu go to `Dev Settings` > `Debug server host & port for device`, and enter your local IP address with port 8081 (eg. `192.168.1.42:8081`). Restart the app, the error should disappear.
193
194
195
196
197
198
199
200

#### Upgrading NDK from `r13b` to `r19`

1. [Download NDK `r19`](https://developer.android.com/ndk/downloads/), unpack it in a convenient location.
1. Update your `NDK_HOME` env variable to the absolute path of the NDK directory.
1. Edit `./android/local.properties` so that `ndk.dir` points to the absolute path to the NDK directory.
1. Remove old NDK build with `rm -rf ./NDK`.
1. Build the new NDK with `./create-ndk-standalone.sh`.
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216

#### Cannot run after upgrade to latest codebase

1. `yarn clean`
2. `yarn install`
3. `cd ios && pod install && cd ..`
4. delete app on device
5. `yarn start --reset-cache`

##### build on iOS
6. in Xcode (be sure to open with `./ios/NativeSigner.xcodeworkspace` file), clean build with `shift + command + K`
7. `yarn run ios`

##### build on Android
6. clean build with `cd android && ./gradlew clean && cd ..`
7. `yarn run android`