uport-connect

Quick Start | Tutorial and Examples | Usage Guide | Development Guide | Contributing

Introduction

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.

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.

For more information about our system and other products visit uport.me. View our whitepaper draft if interested in understanding all the components of our identity system, how they interact and for the background of why many choices were made. Please be aware this document is rapidly changing at the moment. Our uPort mobile app is currently in a limited alpha release, you can sign up here for IOS or Android. If you are interested in partnering with uPort please reach out here.

For any questions or library support reach out to the uPort team on gitter or create a Github issue.

---

Getting started with uPort

For additional documentation on all functionality visit our docs. For a quick start continue below.

For a more interactive quick start visit developer.uport.me

Quick Start

npm install uport-connect

First we will instantiate the uPort object.

import { Connect } from 'uport-connect'

const uport = new Connect('MyDApp')

To ask the user for their credentials use requestCredentials(). With no additional params this will return a user's public profile.

uport.requestCredentials().then((credentials) => {
  console.log(credentials)
})

If all we want is the address of the connected user we can use requestAddress():

uport.requestAddress().then((address) => {
  console.log(address)
})

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.

For a quick setup you may also request a remote copy from unpkg CDN as follows:

<!-- The most recent version  -->
<script src="https://unpkg.com/uport-connect/dist/uport-connect.js"></script>
<!-- The most recent minified version  -->
<script src="https://unpkg.com/uport-connect/dist/uport-connect.min.js"></script>
<!-- You can also fetch specific versions by specifying the version, files names may differ for past versions -->
<script src="https://unpkg.com/uport-connect@<version>/dist/uport-connect.js"></script>

To see all available dist files on unpkg, vist unpkg.com/uport-connect/dist/

Then to instantiate the uPort object from the browser window object:

var uportconnect = window.uportconnect
var uport = new uportconnect.Connect('MyDApp')

Tutorial and Examples

For a more in depth quick start example follow our tutorial for building a simple friend wallet or locally open the /tutorial folder. This simple example will show you how to use our default QR flow to fetch a user's contacts and create transactions to send ether to those contacts.

For additional code examples look in /examples. For a quick start example:

git clone https://github.com/uport-project/uport-connect
cd uport-connect
npm install
npm run build-dist
open examples/example.html

---

Usage Guide

The following Connect object is the primary interface you will use. All details and additional documentation can be found in our docs.

• Connect ⇐ ConnectCore
  • new Connect(appName, [opts])
  • .getWeb3() ⇒ web3
  • .getProvider() ⇒ UportSubprovider
  • .requestCredentials([request], [uriHandler]) ⇒ Promise.<Object, Error>
  • .requestAddress([uriHandler]) ⇒ Promise.<String, Error>
  • .attestCredentials(credential, [uriHandler]) ⇒ Promise.<Object, Error>
  • .request(request) ⇒ Promise.<Object, Error>
  • .contract(abi) ⇒ Object
  • .sendTransaction(txobj) ⇒ Promise.<Object, Error>
  • .addAppParameters(txobj, callbackUrl) ⇒ Promise.<Object, Error>

Communication

This library manages communication between your application and the mobile app. This communication channel differs depending on the environment in which your app runs and the parameters which you specify. In general, communication consist of a request and a response. This library helps you encode all supported requests. The mobile app understands requests encoded as Uniform Resource Identifier's (URI) with a set of params. These URIs are the strings which must be communicated to the mobile device. All functions which create a request will call a uriHandler function which consumes this URI string. This uriHandler allows both default and custom means of display and communication.

Default QR flow

When the library is loaded on a non-mobile device the library will use QR codes to pass information to the mobile application. To receive a response the library will query a messaging server. You will be able to run your own messaging server or utilize other communication channels, but by default this is provided. We provide a default QR-code display function, which injects a <div> containing the QR-code into the DOM. Any function which makes a request to the mobile app will bring up this QR flow.

Using the default QR is the quickest way to start but in many cases you may want to change the QR display, embed the QR codes in different parts of your app, change the display depending on the request, or generate QR codes in once place and show them in another. We provide flexible configs to meet your needs. You can set a default uriHandler to be used with every request from the instantiated Connect object or you can can pass a uriHandler with each function call which makes a request. The functions which create a request should be clear from the docs.

Instantiate a Connect object with a default uriHandler. This URI handler will be called with the request URI on every request.

const uport = new Connect('MyDApp', {
  uriHandler: (uri) => {
    // ex. show URI handler, create QR code or create a button to send a user to the mobile app
  }
})

Every function which creates a request can be given a uriHandler. When given a URI handler it will ignore the default uriHandler with which the object was instantiated.

const uriHandler = (uri) => {
  // ex. show URI handler, create QR code or create a button to send a user to the mobile app
}
uport.requestCredentials({}, uriHandler).then((credentials) => {
  // requestCredentials will call uriHandler with a request encoded as URI string
})

URIs are not QR code URIs. If you want to generate a QR code from these request URIs, you can use the following function provided in this library.

import { QRUtil } from 'uport-connect'

const uriHandler = (uri) => {
  // Creates a QR code URI, this is also a good place to you used any QR code library you prefer.
  const qrCode = QRUtil.getQRDataURI(uri)
  // A QR cod URI can then be used in a html img tag <img src="${qrCode}"/>
}

Default Mobile Requests

By default uport-connect will detect if the library is loaded on a mobile device. When on a mobile device it will call the default mobileUriHandler function which consumes a URI encoded request. When on a mobile device it assumes that the uPort app is on the same device, it will set the window URL to the request URI which will bring up a prompt to open that URI in the uPort app. To return a response the mobile app will call a URL which encodes the response and return control to the calling app. There is also a great deal of flexibility with the mobileUriHandler, the following options may be useful.

Instantiate a Connect object with a default mobileUriHandler. This mobile URI handler will be called with the request URI on every request from a mobile device.

const uport = new Connect('MyDApp', {
  mobileUriHandler: (uri) => { ... }
})

If you want all requests to be handled by your own uriHandler. For example you many not want to rely on our default device detection and include your own or set different rules. If you know your application will always be run on a particular device, for example in a native app then this is also useful.

const uport = new Connect('MyDApp', {
  isMobile: false
})
// Then set a default uriHandler or pass a uriHandler for each function which makes a request

Push Notifications

An alternative means to communicate with a user's uPort app is through push notifications. This requires an initializing request using one of the flow above, then all requests can be made with push notifications. Using push notification requests requires requesting an additional permission from a uPort user. Thus only use push notifications when you believe it improve your app's user experience and/or your application has some limiting factor that necessitates use. (for example requests which are too large to place in a QR code).

uport.requestCredentials({
  notifications: true
}).then((credentials) => { ... })
// Then all future requests will use push notifications if permission is granted.

Ethereum Interactions and Transactions

uport-connect can be used to create a web3 object wrapped with uPort functionality. If you already have an existing application built on ethereum using web3 then this may be the simplest uPort integration. If you want to use alternatives to web3 then uport-connect can create a web3 style provider wrapped with uPort functionality and can be used in any library which supports these providers, for example ethjs. If you have no need to use web3, or want more granular control over handling request URIs, then uport-connect provides a contract object similar to web3 which can be used to create transactions encoded as URI requests.

Using with web3

We provide a convenience method to create a uPort enabled version of the web3 object:

let web3 = uport.getWeb3()

After the above setup, you can now use the web3 object as normal.

The following calls will initiate a uPort request, by default this will show a QR code.

• web3.eth.getCoinbase() - returns your uport address, if not set already
• web3.eth.getAccounts()- returns your uport address in a list, if not set already
• web3.eth.sendTransaction(txObj) - returns a transaction hash
• myContract.myMethod() - returns a transaction hash

Using a provider

Create a web3 style provider to use with web3 or other libraries which support these providers. Intercepts the same RPC calls as defined above for the web3 object.

const uportProvider = uport.getProvider()

Contract Object (without web3)

Primary reasons to use this object include; 1) You don't want/need to use web3 2) Using a web3 object will use your default URI handler for every request, if you want different URI handling for different contracts or different contract function calls then you should use this. Each contract function call consumes a uriHandler function.

Functionality and use similar to web3 contract object. This contract object is promised based.

  const statusContractABI = [
      {
        "constant": false,
        "inputs": [
          {
            "name": "status",
            "type": "string"
          }
        ],
        "name": "updateStatus",
        "outputs": [],
        "type": "function"
      }
    ]

  const statusContract = uport.contract(statusContractABI)
  const status = statusContract.at("0xB42E70a3c6dd57003f4bFe7B06E370d21CDA8087")

  const uriHandler = (uri) => {
    // ex. show URI handler, create QR code or create a button to send a user to the mobile app
  } slack

  status.updateStatus('hello', uriHandler).then(txhash => {
    ...
  })

---

Development Guide

Run Locally

Download this repo or your fork, then run npm install.

Builds

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

$ 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

$ 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

$ npm run build-dist-prod

Tests

We write our tests using mocha and run them with karma. TestRPC runs in the background during tests.

To run our tests:

$ npm run karma

Code Coverage

Code coverage reports are generated when tests are run and can be viewed in browser. Reports are also published on CodeCov when pushed to github.

$ npm run karma
$ open test/coverage/html/index.html

Linting

Run our linter, we follow JavaScript Standard Style.

$ npm run lint

Documentation

We write inline documentation using JSDoc. To generate docs:

$ npm run build:docs:html
$ open docs/index.html

$ npm run build:docs:md // to generate a DOCS.md markdown file

Scripts

Additional scripts can be found in package.json -> scripts: { }.

Versioning

We follow MAJOR.MINOR.PATCH Semantic Versioning

NPM Install Develop branch

You can npm install the develop branch of uport-connect using the follow commands.

$ npm install "git://github.com/uport-project/uport-connect.git#develop" --save
$ (cd node_modules/uport-connect && npm install babel-cli && npm run prepublish)

Contributing

Code, test and documentation contributions are welcomed and encouraged. Please read the guidelines below and reach out on gitter or create an issue if any contribution is more than trivial. We can help you see where/if it fits into our roadmap and if we are likely to accept. We are also looking to add references to projects using uport-connect with example implementations and use cases.

Reporting Bugs

Well formed bug reports are hugely valuable to the project and allow us quickly evaluate and fix a bug. Poorly formed bug reports leave use searching for more details and even worse may leave us trying to resolve bugs not related to the code here. Primarily be thoughtful when submitting bugs and leave enough details to minimize the paths we have to take when finding a resolution. Report bugs by creating an issue.

Some guidelines for reporting bugs:

• Make sure that your issue is caused by uport-connect and not your application code.
• Create a simple and minimal test case that demonstrates the bug.
• Search the issues to see if the bug has already been reported. If it has, add any additional details in the comments.
• Write a descriptive and specific title.
• Include browser, OS, uport-connect version and any other details specific to the environment.
• Check whether the bug can be reproduced in other environments (ie. other browsers).

Contributing code

Our master branch reflects our most recent release, while we accept pull requests from topic branches into our develop branch. To submit code for a feature, bug or documentation, fork this repo and add all related commits to a topic branch (feature/your-title, fix/your-title, doc/your-title, etc). Once ready for review, open a pull request to merge into develop.

All commits are required to be well formed. We follow the AngularJS Commit Message Conventions. We use these commit messages to create a useful history, generate CHANGELOGS and to determine release versions.

Before submitting your changes run npm run lint to find any formatting issues that don't adhere to the original codebase. Run npm run karma to be sure all tests pass. When submitting a bug fix try to add additional tests to cover that bug or similar bugs in the future. If a bug was specific to an environment consider adding a environment specific note in the docs. When submitting code for a new feature or functionality add the relevant documentation and test coverage as well.