Merge pull request #223 from uport-project/release/v1.0.0

Release/v1.0.0

.babelrc

@@ -2,11 +2,12 @@
   "env": {
     "production": {
       "plugins": ["transform-es2015-modules-umd"]
-    }
+    }, 
   },
   "presets": ["es2015"],
   "plugins": [
     "syntax-object-rest-spread",
-    "transform-object-rest-spread"
+    "transform-object-rest-spread", 
+    "istanbul"
   ]
 }

README.md

@@ -8,57 +8,160 @@
 
 [Quick Start](#quick-start) | [Tutorial and Examples](#tutorials) | [Usage Guide](#usage-guide) | [Development Guide](#development-guide) | [Contributing](#contribute)
 
-# <a name="introduction"></a> Introduction
+**Required Upgrade v1.0.0 or ^0.7.5**
+
+**^0.7.5 to support new both new uPort Mobile Clients and legacy uPort Mobile Clients - [View Details](https://github.com/uport-project/uport-connect/releases/tag/v0.7.5)**
 
-**Required Upgrade to v0.7.5 to support new uPort Clients - [View Details](https://github.com/uport-project/uport-connect/releases/tag/v0.7.5)**
+**v1.0.0 to support only new uPort Mobile Clients and to use new features and fixes**
 
-**uPort** is a system for self-sovereign digital identity anchored in Ethereum.
-The uPort technology primarily consists of smart contracts, developer libraries, and a mobile app. uPort identities are fully owned and controlled by the creator, and don't rely on centralized third-parties for creation, control or validation. In the current implementation of the system this is achievable by having the mobile app act as the primary secure container for data related to your identity and for a set of keys which allow you sign transactions, grant authorization and sign credentials. The identity is anchored in the blockchain with an identifier and public data is stored in IPFS.
+:bangbang: :warning: **v1.0.0** is released at the npm next tag at **uport-connect@next**. Only the newest uPort Mobile Client release will work with **v1.0.0**. It will become the default release once the newest uPort Mobile Client release is widely adopted (~ 2 weeks). Reference master branch for docs and info on current default release **v0.7.5**. Documentation for **v1.0.0** can only be found here and in the docs folder. The [developer site](https://developer.uport.me) will not contain **v1.0.0** documentation until it is the default release :warning: :bangbang:
+
+# <a name="introduction"></a> Introduction
 
-`uport-connect` is the client side library that allows you interact with user's uPort identities through the mobile app. It handles the communication channel between your app and the uPort mobile app, which can vary depending on the environment which your application runs. Over this communication channel you can create requests for a user's data, share credentials and generate transactions to be signed in the user's mobile app.
+**uPort** is a collection of tools and protocols for building decentralized user-centric applications. It is built on open standards and open source libraries. uPort identities can be created and interacted with through uPort clients, including the uPort mobile app. Identities are fully owned and controlled by the creator, and don't rely on centralized third-parties for creation, control or validation.
 
-For more information about our system and other products visit [uport.me](https://www.uport.me). View our [protocol specs](https://github.com/uport-project/specs/) if interested in understanding some of the lower level details.
+`uport-connect` is the client side library that allows you interact with a user's uPort identity through a uPort client, primarily the mobile app. It handles the communication channel between your app and a uPort client, which can vary depending on the environment which your application runs. Over this communication channel you can send requests for a user's data, share credentials, generate transactions to be signed by a user and relay requests you originally created on your server with [uport-credentials](https://github.com/uport-project/uport-credentials). This library offers the default quick start implementation to integrate with uPort, but if it doesn't offer exactly what you need, you may be interested in using [uport-tranports](https://github.com/uport-project/uport-transports) and [uport-credentials](https://github.com/uport-project/uport-credentials) instead.
+
+For more information about our system and other products visit [uport.me](https://www.uport.me). View our [protocol specs](https://github.com/uport-project/specs/) if interested in understanding the lower level details.
 
 For any questions or library support reach out to the [uPort team on riot](https://chat.uport.me/#/login) or create a [Github issue](https://github.com/uport-project/uport-connect/issues).
 
 ---------------------------------------------
 
 ## <a name="getting-started"></a>Getting started with uPort
 
-For additional documentation on all functionality [visit our docs](https://github.com/uport-project/uport-connect/blob/develop/docs/reference/index.md). For a quick start continue below.
-
-For a more interactive quick start visit [developer.uport.me](https://developer.uport.me/gettingstarted)
+For additional documentation on all functionality [visit our docs](https://github.com/uport-project/uport-connect/blob/develop/docs/reference/index.md). For a more interactive intro visit [developer.uport.me](https://developer.uport.me/gettingstarted). For a quick start continue below.
 
 ### <a name="quick-start"></a> Quick Start
 
 ```shell
 npm install uport-connect
 ```
 
-First we will instantiate the uPort object, by default it is configured on the Rinkeby test network.
+First we will instantiate the uPort object, by default it is configured on the Rinkeby test network, reference the docs for additional config arguments which can be passed.
 
 ```javascript
 import { Connect } from 'uport-connect'
+const uport = new Connect('MyDAppName')
+// or on mainnet
+// const uport = new Connect('MyDAppName', {network: 'mainnet'})
+```
 
-const uport = new Connect('MyDApp')
+To request the DID and address of user use `requestDisclosure()`:
+
+```javascript
+uport.requestDisclosure({})
+
+uport.onResponse('disclosureReq').then(res => {
+  const did = res.payload.did
+  ...
+})
 ```
 
-To ask the user for their credentials use `requestCredentials()`. With no additional params this will return a user's public profile.
+Or to request addtional credentials, along with the DID.
 
 ```javascript
-uport.requestCredentials().then((credentials) => {
-  console.log(credentials)
+const reqObj = { requested: ['name', 'country'],
+                  notifications: true }
+
+uport.requestDisclosure(reqObj)
+
+uport.onResponse('disclosureReq').then(res => {
+  const did = res.payload.did
+  const verified = res.payload.verified // An array of shared verified credentials, matching requested
+  ...
 })
 ```
 
-If all we want is the address of the connected user we can use `requestAddress()`:
+uPort Connect will save session data and data from prior requests to localStorage and will load it on instantiation. You can check if it is available before creating a selective disclosure request again.
 
 ```javascript
-uport.requestAddress().then((address) => {
-  console.log(address)
+if (uport.did) {
+  // Already connected, reference docs to see data which will be available
+} else {
+  // Create a request if necessary
+}
+```
+
+To send a request message (JWT) you created on your server or elsewhere use `send()`:
+
+```javascript
+const reqID = 'myRequestID'
+const request = `eyJ0eXAiOiJKV1QiLCJhbG...`
+uport.send(request, reqID)
+uport.onResponse(reqID).then(payload => {
+  // Response is available now, handle as necessary to your implementation
+  // If the response was returned your server, you may poll for it now
 })
 ```
 
+To request a user to sign a claim
+
+```javascript
+const unsignedClaim = {
+    "Citizen of city X": {
+      "Allowed to vote": true,
+      "Document": "QmZZBBKPS2NWc6PMZbUk9zUHCo1SHKzQPPX4ndfwaYzmPW"
+    }
+}
+
+const sub ="did:ethr:0x413daa771a2fc9c5ae5a66abd144881ef2498c54"
+
+uport.requestVerificationSignature(unsignedClaim, sub)
+
+uport.onResponse('verSigReq').then(res => {
+  const signedClaim = res.payload
+})
+```
+
+To create a transaction request use `contract()` or `sendTransaction()`:
+
+```javascript
+const abi = [{"constant": false,"inputs": [{"name": "status","type": "string"}],"name": "updateStatus","outputs": [],"type": "function"}]
+const contractAddress = '0x71845bbfe5ddfdb919e780febfff5eda62a30fdc'
+const statusContract = uport.contract(abi).at(contractAddress)
+
+statusContract.updateStatus('hello', 'updateStatusReq')
+uport.onResponse('updateStatusReq').then(payload => {
+  const txId = payload.res
+})
+```
+
+```javascript
+const txObj = {
+  address: '0x71845bbfe5ddfdb919e780febfff5eda62a30fdc',
+  value: 1 * 1.0e18
+}
+uport.sendTransaction(txObj, 'ethSendReq')
+uport.onResponse('ethSendReq').then(res => {
+  const txId = res.payload
+})
+```
+### <a name="quick-start"></a> Quick Start with Provider (web3)
+
+Get provider and instantiate web3 or other provider supported library.
+
+```javascript
+const provider = uport.getProvider()
+const web3 = new Web3(provider)
+```
+
+To request the address of user:
+
+```javascript
+web3.eth.getCoinbase((error, address) => { ... })
+```
+
+To call contract:
+```javascript
+const statusContract = web3.eth.contract(abi).at(contractAddress)
+statusContract.updateStatus('hello', (error, txHash) => { ... })
+```
+
+To send transaction:
+```javascript
+web3.eth.sendTransaction(txObj, (error, txHash) => {...})
+```
 ### <a name="browser-quick-start"></a> Browser Window Quick Start
 
 For use directly in the browser you can reference the uport-connect distribution files from a number of places. They can be found in our npm package in the 'dist' folder or you can build them locally from this repo.
@@ -78,8 +181,8 @@ To see all available dist files on unpkg, vist [unpkg.com/uport-connect/dist/](h
 Then to instantiate the uPort object from the browser window object:
 
 ```js
-var uportconnect = window.uportconnect
-var uport = new uportconnect.Connect('MyDApp')
+const Connect = window.uportconnect
+const uport = new Connect('MyDApp')
 ```
 
 ### <a name="tutorials"></a> Tutorial and Examples
@@ -98,40 +201,40 @@ Download this repo or your fork, then run `npm install`.
 
 All builds are created from files in `/src`
 
-To transpile to ES5. All files are output to `/lib`. The entry of our npm package is `/lib/index.js`
+To transpile to ES5. All files are output to `/lib`. The entry of our npm package is `/lib/Connect.js`
 
 ```shell
-$ npm run build-es5
+$ npm run build:es5
 ```
 
 To generate a bundle/distributable. We use webpack for our builds. The output dist is `/dist/uport-connect.js` and source map `/dist/uport-connect.map.js`
 
 ```shell
-$ npm run build-dist
+$ npm run build:dist
 ```
 
 To generate a production bundle/distributable. Includes build optimizations related to size and code is minified. The output dist is `/dist/uport-connect.min.js` and source map `/dist/uport-connect.min.map.js`
 
 ```shell
-$ npm run build-dist-prod
+$ npm run build:dist:prod
 ```
 
 #### <a name="test"></a> Tests
 
-We write our tests using [mocha](http://mochajs.org) and run them with [karma](https://karma-runner.github.io/1.0/index.html). [TestRPC](https://github.com/ethereumjs/testrpc) runs in the background during tests.
+We write our tests using [mocha](http://mochajs.org) and run them with [karma](https://karma-runner.github.io/1.0/index.html).
 
 To run our tests:
 
 ```shell
-$ npm run karma
+$ npm test
 ```
 
 #### <a name="coverage"></a> Code Coverage
 
 Code coverage reports are generated when tests are run and can be viewed in browser. Reports are also published on [CodeCov](https://codecov.io/gh/uport-project/uport-connect) when pushed to github.
 
 ```shell
-$ npm run karma
+$ npm test
 $ open test/coverage/html/index.html
 ```
 

.circleci/config.yml → circle.yml

@@ -18,15 +18,15 @@ jobs:
 
       - run:
           name: test
-          command: npm run karma-CI
+          command: npm run test
 
       - run:
           name: code-coverage
           command: bash <(curl -s https://codecov.io/bash)
 
       - run:
           name: dist
-          command: npm run build-dist && npm run build-dist-prod
+          command: npm run build:dist && npm run build:dist:prod
 
       - save_cache:
           key: dependency-cache-{{ checksum "package.json" }}

docs/guides/tutorial.md

@@ -1,24 +1,24 @@
 ---
-title: "How to integrate Uport-Connect"
-index: 0
-category: "tutorials"
-type: "content"
+title: "How to Integrate with Web3"
+index: 3
+category: "uport-connect"
+type: "tutorial"
 source: "https://github.com/uport-project/uport-connect/blob/develop/docs/guides/tutorial.md"
 ---
 
-# How to integrate uPort into your dapp
+# How to Integrate uPort Into Your dApp
 
 ## Introduction
 
-This tutorial will show you how to add support for uPort in your decentralized Ethereum application. Using the `uport-connect` library, we will create a simple application. This application will let you connect your uPort, send simple Ether transactions and set a simple status message in a smart contract.
+This tutorial will demonstrate how you can integrate uPort into your decentralized Ethereum application. Using the `uport-connect` library, we will create a simple application; this application will allow you to integrate uPort, send simple Ether transactions, and set a simple status message in a smart contract.
 
-We will assume some familiarity with creating Ethereum applications using the `web3` library.
+In this tutorial, we assume some basic familiarity with creating Ethereum applications using the `web3` library.
 
-*Note: The examples provided inline here and in the example files use ES6. Although our library is also written in ES6, it is transpiled to ES5, thus is perfectly compatible if you choose to use ES5 instead. These examples are simple to change to ES5 if your needs require.*
+*Note: The examples provided inline here and in the example files, use ES6. Although our library is written in ES6, it is transpiled to ES5. Thus it’s perfectly compatible with ES5 if you prefer to use that instead. These examples are simple to change to ES5 if your needs demand it*
 
-## Getting started
+## Getting Started
 
-Clone the `uport-connect` repository locally, and build it:
+Make sure you have the uPort application installed on your mobile device. Afterward, clone the `uport-connect` repository locally and build it using:
 
 ```sh
 git clone https://github.com/uport-project/uport-connect
@@ -27,30 +27,31 @@ npm install
 npm run build-dist
 ```
 
-We will be working in the directory `uport-connect/examples/integration-tutorial`.
+We will be working in the `uport-connect/examples/integration-tutorial` directory.
 
 Make sure you have the uPort application installed on your mobile device.
 
-We've provided a simple HTML file `uport_tutorial.html` that you can find [here](https://github.com/uport-project/uport-connect/blob/develop/tutorial/uport_tutorial.html). It contains a section for connecting your uPort, one section for a transfer of Ether from your uPort address to another address and a section that sets a simple status message in a smart contract.
+We've provided a simple HTML file `uport_tutorial.html` that you can find [here](https://github.com/uport-project/uport-connect/blob/develop/tutorial/uport_tutorial.html). It contains a section for connecting your uPort, a section for transferring Ether from your uPort address to another address, and a section that sets a simple status message in a smart contract.
 
-In order to test the dapp, all you need to do is open the file `uport_tutorial.html` in a browser. There is a file `index.js` that will contain the JavaScript integration code.
+To test the dApp, all you need to do is open the `uport_tutorial.html` file in your browser. There is a file named `index.js` that will contain the JavaScript integration code that you need.
 
 Consider the necessary code to set up the `web3` object with the uPort provider:
 
 ```js
 const Connect = window.uportconnect.Connect
 const appName = 'UportTutorial'
 const connect = new Connect(appName, {network: 'rinkeby'})
-const web3 = connect.getWeb3()
+const provider = connect.getProvider()
+const web3 = new Web3(provider)
 ```
 
-The uPort library sets up the web3 object using a web3 provider. This is the mechanism that interprets calls to web3 functions and this is what will trigger the QR codes for connecting your uPort and signing transactions.
+The uPort library sets up the web3 object using a web3 provider. This is the mechanism that interprets calls to web3 functions, and this is what will trigger the QR codes for connecting your uPort and signing transactions.
 
 The `uportConnect()` function will trigger the "login" and populate the user's uPort address in the UI.
 
-Load the HTML file in your browser and hit "Connect uPort". You should see a QR code come up. When you scan it with the uPort app you should see your uPort address being populated in the UI.
+Load the HTML file in your browser and hit "Connect uPort". You should see a QR code appear on the screen. When you scan it with the uPort app, you should see your uPort address populated in the UI.
 
-The functions that trigger QR codes are
+The functions that trigger QR codes are:
 
 ```js
 web3.eth.getCoinbase() //returns your uport address
@@ -59,10 +60,10 @@ web3.eth.sendTransaction(txObj) //returns a transaction hash
 myContract.myMethod() //returns a transaction hash
 ```
 
-The functions `getAccounts()` and `getCoinbase()` trigger the QR code that brings up the "connect" QR code, or if you have already connected, the address is stored in the uport provider object and will be returned without showing the QR code. Due to this behaviour it is recommended to have a place in your dapp where the user can "log in" or "connect". If you call `getCoinbase()` right before it's needed (like right before sending a transaction) the user experience is not as good since the user needs to scan two QR codes in rapid succession.
+The functions `getAccounts()` and `getCoinbase()` trigger the QR code that brings up the "connect" QR code; if you are already connected, the address is stored in the uPort provider object and will return without showing the QR code. Due to this behavior, we suggest that you have a place in your dApp where the user can "log in" or "connect". If you call `getCoinbase()` before it's needed (e.g., right before sending a transaction), the user experience won’t be ideal, since the user needs to scan two QR codes in rapid succession.
 
-The functions for sending ETH and setting the status are exactly how you would write them in vanilla `web3.js`. In order to send ETH you need to first fetch some Rinkeby Ether at the Rinkeby Faucet available here: <https://rinkeby.io>.
+The functions for sending ETH and setting the status are exactly how you would write them in vanilla `web3.js`. To send ETH, you must first fetch some Rinkeby Ether at the Rinkeby faucet, available here: <https://rinkeby.io>.
 
-Try sending some Rinkeby ETH and setting the status! You should see QR codes appear when it's time to sign transactions, and you use your uPort app to scan them. After sending and setting the status you can reload the page and connect again to make sure the balance and status was updated.
+Now, try sending some Rinkeby ETH and setting the status. You will see QR codes appear when it's time to sign transactions, and you use your uPort app to scan them. After sending and setting the status, you can reload the page and reconnect, to make sure the balance and status are updated.
 
-You should now have a basic grasp of implementing uPort in your Dapp!
+We hope that you now have a basic grasp of how to go about implementing uPort into your dApp :)