Introduction

Uport is a system for self-sovereign digital identity.

This is the client side library that is used to interact with the mobile application where the end-user's keys are stored.

Signing transactions thus requires that the transactions are sent to the phone where they can be signed. This is accomplished by showing the user a QR-code for each transaction. The user can then verify the transaction on the phone and send it to the Ethereum network.

In order to make this flow easy for developers, uport-connect provides a custom web3 provider which takes care of all of this.

Using uPort in your Application

Getting Started

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():

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)
})

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/uportconnect.js"></script>
<!-- The most recent minified version  -->
<script src="https://unpkg.com/uport-connect/dist/uportconnect.min.js"></script>
<!-- You can also fetch specific versions by specifying the version -->
<script src="https://unpkg.com/uport-connect@0.4.5/dist/uportconnect.js"></script>

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

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

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.

Also, the following calls will show a QR code for the user to scan:

web3.eth.getCoinbase() - returns your uport address
web3.eth.getAccounts()- returns your uport address in a list
web3.eth.sendTransaction(txObj) - returns a transaction hash
myContract.myMethod() - returns a transaction hash

Check out the examples folder too for how to integrate uport in your DApp

Customizing QR code requests

uport-connect features a default QR-code display function, which injects a <div> containing the QR-code into the DOM. However, you might want to display the QR-code in a different way.

You can provide your own uriHandler function which can be used to handle it your self using your own frontend library.

const uport = new Connect('MyDApp', {
  uriHandler: (uri) => {
    // show URI handler or button to send user to mobile app
  }
})

Contributing

Testing / Building (& watching) / Docs

This basic commands can be found in package.json -> scripts: { } for contributing to the library.

npm install from Github

To install this package from Github and the develop branch:

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

jamesyoung / uport-connect