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-lib provides a custom web3 provider which takes care of all of this.

Using uPort in your dapp

Getting Started

First we will instantiate the Uport and Web3 objects. Then we will get the information of the connected user. Since the information of the connected user is stored on ipfs we need to provide uport-lib with an ipfs provider upon on creation of Uport instance. Here we use Infura as an example.

import Web3 from 'web3'
import { Uport } from 'uport-lib'

let web3 = new Web3()
let options = {
  ipfsProvider: {
    host: 'ipfs.infura.io',
    port: '5001',
    protocol: 'https',
    root: ''
  }
}
let uport = new Uport('MyDApp', options)
let rpcUrl = "http://localhost:8545"
let uportProvider = uport.getUportProvider(rpcUrl)

web3.setProvider(uportProvider)

uport.getUserPersona()
     .then((persona) => {
       let profile = persona.getProfile()
       console.log(profile)
     })

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

Custom Display of QR codes

uport-lib 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 a qrDisplay object with two functions when uport is created. The openQr function is called when the user needs to confirm something on the uport app. The data argument is a uri that needs to be displayed in a QR-code so that the uport app can scan it. The closeQr function is called when the action has been confirmed in the uport app and the QR-code can be removed from the screen.

let options = {
  ipfsProvider: { ... }
  qrDisplay: {
    openQr(data) { // your code here },
    closeQr() { // your code here }
  }
}

The openQr function is called each time some information needs to get to the phone.

The closeQr is called once the phone has taken an action on the data in the QR-code.

Interacting with persona objects of other users

You can also import the Persona and the MutablePersona classes from uport lib to interact with any persona in the uport-registry.

import { Persona, MutablePersona } from 'uport-lib'

let userAddress = "0x..."
let ipfsProvider = { ... }
let persona = new Persona(userAddress, ipfsProvider, web3.currentProvider)
persona.load()
       .then((attributes) => {
         console.log(attributes)
       })

More information on how to use personas can be found in the uport-persona repo, or by reading the documentation below.

Contributing

Testing / Building (& watching) / Docs

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

npm run test
npm run build
npm run watch
npm run gen-readme

Documentation

Uport

This class is the main entry point for interaction with uport.

Kind: global class

Uport
- .constructor(dappName, opts) ⇒ Object
- .getUportProvider(rpcUrl) ⇒ Object
- .getUportProvider() ⇒ Object
- .setProviders(web3Provider, ipfsProvider)
- .getUserPersona() ⇒ Promise.<MutablePersona>

Uport.constructor(dappName, opts) ⇒ `Object`

Creates a new uport object.

Kind: static method of Uport
Returns: Object - self

Param	Type	Description
dappName	`String`	the name of your dapp
opts	`Object`	optional parameters
opts.qrDisplay	`Object`	custom QR-code displaying
opts.registryAddress	`String`	the address of an uport-registry
opts.ipfsProvider	`Object`	an ipfsProvider
opts.chasquiUrl	`String`	a custom chasqui url

Uport.getUportProvider(rpcUrl) ⇒ `Object`

Get the uport flavored web3 provider. It's implemented using provider engine.

Kind: static method of Uport
Returns: Object - the uport web3 provider

Param	Type	Description
rpcUrl	`String`	the rpc client to use

Uport.getUportProvider() ⇒ `Object`

Get the subprovider that handles signing transactions using uport. Use this if you want to customize your provider engine instance.

Kind: static method of Uport
Returns: Object - the uport subprovider

Uport.setProviders(web3Provider, ipfsProvider)

A method for setting providers if not done previously. This is useful if you are using a custom provider engine for example. Not that the ipfsProvider can also be set in the constructor.

Kind: static method of Uport

Param	Type	Description
web3Provider	`Object`	the web3 provider to use (optional)
ipfsProvider	`Object`	the ipfs provider to use (optional)

Uport.getUserPersona() ⇒ `Promise.<MutablePersona>`

This method returns an instance of MutablePersona of the current uport user.

Kind: static method of Uport
Returns: Promise.<MutablePersona> - a MutablePersona instantiated with the address of the connected uport user

Persona

Class representing a persona.

Kind: global class

Persona
- .constructor(address, ipfsProvider, web3Provider, [registryAddress]) ⇒ Object
- .loadAttributes() ⇒ Promise.<JSON, Error>
- .load(claims) ⇒ Promise.<JSON, Error>
- .getProfile() ⇒ JSON
- .getPublicSigningKey() ⇒ String
- .getPublicEncryptionKey() ⇒ String
- .getAllClaims() ⇒ JSON
- .getClaims(attributesName) ⇒ JSON
- .signAttribute(attribute, privSignKey, issuerId) ⇒ Object
- .signMultipleAttributes(attribute, privSignKey, issuerId) ⇒ Array
- .isTokenValid(token) ⇒ Boolean
- .privateKeyToPublicKey(privateKey) ⇒ String

Persona.constructor(address, ipfsProvider, web3Provider, [registryAddress]) ⇒ `Object`

Class constructor. Creates a new persona object. The registryAddress is an optional argument and if not specified will be set to the default consensys testnet uport-registry.

Kind: static method of Persona
Returns: Object - self

Param	Type	Default	Description
address	`String`		the address of the persona
ipfsProvider	`String`		an ipfs provider
web3Provider	`String`		web3 provider
[registryAddress]	`String`	`'0xa9be82e93628abaac5ab557a9b3b02f711c0151c'`	the uport-registry address to use.

Persona.loadAttributes() ⇒ `Promise.<JSON, Error>`

This should be the only function used to get attributes from the uport-registry. This can be overridden in a subclass.

Kind: static method of Persona
Returns: Promise.<JSON, Error> - A promise that returns all tokens registered to the persona. Encrypted tokens would be included here. Or an Error if rejected.

Persona.load(claims) ⇒ `Promise.<JSON, Error>`

This function always have to be called before doing anything else, with the exception of setProfile. This function loads the profile of the persona from the uport-registry into the persona object.

Kind: static method of Persona
Returns: Promise.<JSON, Error> - A promise that returns all tokens registered to the persona. Encrypted tokens would be included here. Or an Error if rejected.

Param	Type	Description
claims	`Object`	A list of claims. If argument is not given the persona will load from the registry.

Persona.getProfile() ⇒ `JSON`

This function returns the profile of the persona in JSON format.

Kind: static method of Persona
Returns: JSON - profile

Persona.getPublicSigningKey() ⇒ `String`

Returns the public signing key of the persona.

Kind: static method of Persona

Persona.getPublicEncryptionKey() ⇒ `String`

Returns the public encryption key of the persona, if set.

Kind: static method of Persona

Persona.getAllClaims() ⇒ `JSON`

Returns all tokens associated with the persona.

Kind: static method of Persona
Returns: JSON - List of tokens

Persona.getClaims(attributesName) ⇒ `JSON`

Returns all tokens that have the given attribute name.

Kind: static method of Persona
Returns: JSON - List of tokens

Param	Type	Description
attributesName	`String`	the name of the attribute to check

Persona.signAttribute(attribute, privSignKey, issuerId) ⇒ `Object`

Signs the given attribute to the persona. This method is to be used by third parties who wishes to attest to an attribute of the persona.

Kind: static method of Persona
Returns: Object - token

Param	Type	Description
attribute	`Object`	the attribute to add, in the format {attrName: attr}
privSignKey	`String`	the private signing key of the attestor
issuerId	`String`	the address of the attestor (voluntary, to allow finding info on the attestor from uport-registry)

Persona.signMultipleAttributes(attribute, privSignKey, issuerId) ⇒ `Array`

Same as addAttribute but for a list of attributes.

Kind: static method of Persona
Returns: Array - List of tokens

Param	Type	Description
attribute	`Array`	the attribute to add, in the format [{attrName: attr},...]
privSignKey	`String`	the private signing key of the attestor
issuerId	`String`	the ethereum address of the attestor

Persona.isTokenValid(token) ⇒ `Boolean`

A static function for checking if a token is valid.

Kind: static method of Persona

Param	Type
token	`Object`

Persona.privateKeyToPublicKey(privateKey) ⇒ `String`

A static function for checking if a token is valid.

Kind: static method of Persona
Returns: String - publicKey

Param	Type
privateKey	`String`

MutablePersona ⇐ `Persona`

Class representing a persona that can be modified.

Kind: global class
Extends: Persona

MutablePersona ⇐ Persona
- .constructor(address, ipfsProvider, web3Provider, [registryAddress]) ⇒ Object
- .writeToRegistry() ⇒ Promise.<String, Error>
- .addClaim(token)
- .addClaims(tokensList)
- .removeClaim(tokens)
- .addAttribute(attribute, privSignKey)
- .replaceAttribute(attribute, privSignKey)
- .removeAttribute(attribute)
- .setPublicSigningKey(privSignKey)
- .setPublicencryptionKey(pubEncKey, privSignKey)

MutablePersona.constructor(address, ipfsProvider, web3Provider, [registryAddress]) ⇒ `Object`

Class constructor. Creates a new persona object. The registryAddress is an optional argument and if not specified will be set to the default consensys testnet uport-registry.

Kind: static method of MutablePersona
Returns: Object - self

Param	Type	Default	Description
address	`String`		the address of the persona
ipfsProvider	`String`		an ipfs provider
web3Provider	`String`		web3 provider
[registryAddress]	`String`	`'0xa9be82e93628abaac5ab557a9b3b02f711c0151c'`	the uport-registry address to use.

MutablePersona.writeToRegistry() ⇒ `Promise.<String, Error>`

This should be the only function ever used to write the persona onto the blockchain. This can be overridden in a subclass.

It stores whatever is in this.tokenRecords.

Kind: static method of MutablePersona
Returns: Promise.<String, Error> - A promise that returns the txHash of the transaction updating the registry. Or an Error if rejected.

MutablePersona.addClaim(token)

Add a signed claim to this persona. This should be used to add tokens signed by third parties.

Kind: static method of MutablePersona

Param	Type	Description
token	`JSON`	the claim to add

MutablePersona.addClaims(tokensList)

Add mulitple signed claims to this persona. This should be used to add tokens signed by third parties.

Kind: static method of MutablePersona

Param	Type	Description
tokensList	`JSON`	the claims to add

MutablePersona.removeClaim(tokens)

Removes a signed claim from a persona.

Kind: static method of MutablePersona

Param	Type	Description
tokens	`JSON`	the claims to add

MutablePersona.addAttribute(attribute, privSignKey)

Adds a self signed attribute to the persona. Only to be used if you own the pubSignKey of this persona.

Kind: static method of MutablePersona

Param	Type	Description
attribute	`Object`	the attribute to add, in the format {attrName: attr}
privSignKey	`String`	the private signing key of the persona

MutablePersona.replaceAttribute(attribute, privSignKey)

Removes all tokens having the same attribute name as the given attribute and adds the given attribute.

Kind: static method of MutablePersona

Param	Type	Description
attribute	`Object`	the attribute to add, in the format {attrName: attr}
privSignKey	`String`	the private signing key of the persona

MutablePersona.removeAttribute(attribute)

Removes all attributes with the same attribute name as the given attribute.

Kind: static method of MutablePersona

Param	Type	Description
attribute	`Object`	the attribute to add, in the format {attrName: attr}

MutablePersona.setPublicSigningKey(privSignKey)

Sets the public signing key of the persona.

Kind: static method of MutablePersona

Param	Type	Description
privSignKey	`String`	the private signing key of the persona

MutablePersona.setPublicencryptionKey(pubEncKey, privSignKey)

Sets the public encryption key of the persona.

Kind: static method of MutablePersona

Param	Type	Description
pubEncKey	`String`	the public encryption key of the persona
privSignKey	`String`	the private signing key of the persona

Files

README.md

Latest commit

History

README.md

File metadata and controls

Introduction

Using uPort in your dapp

Getting Started

Custom Display of QR codes

Interacting with persona objects of other users

Contributing

Testing / Building (& watching) / Docs

Documentation

Uport

Uport.constructor(dappName, opts) ⇒ Object

Uport.getUportProvider(rpcUrl) ⇒ Object

Uport.getUportProvider() ⇒ Object

Uport.setProviders(web3Provider, ipfsProvider)

Uport.getUserPersona() ⇒ Promise.<MutablePersona>

Persona

Persona.constructor(address, ipfsProvider, web3Provider, [registryAddress]) ⇒ Object

Persona.loadAttributes() ⇒ Promise.<JSON, Error>

Persona.load(claims) ⇒ Promise.<JSON, Error>

Persona.getProfile() ⇒ JSON

Persona.getPublicSigningKey() ⇒ String

Persona.getPublicEncryptionKey() ⇒ String

Persona.getAllClaims() ⇒ JSON

Persona.getClaims(attributesName) ⇒ JSON

Persona.signAttribute(attribute, privSignKey, issuerId) ⇒ Object

Persona.signMultipleAttributes(attribute, privSignKey, issuerId) ⇒ Array

Persona.isTokenValid(token) ⇒ Boolean

Persona.privateKeyToPublicKey(privateKey) ⇒ String

MutablePersona ⇐ Persona

MutablePersona.constructor(address, ipfsProvider, web3Provider, [registryAddress]) ⇒ Object

MutablePersona.writeToRegistry() ⇒ Promise.<String, Error>

MutablePersona.addClaim(token)

MutablePersona.addClaims(tokensList)

MutablePersona.removeClaim(tokens)

MutablePersona.addAttribute(attribute, privSignKey)

MutablePersona.replaceAttribute(attribute, privSignKey)

MutablePersona.removeAttribute(attribute)

MutablePersona.setPublicSigningKey(privSignKey)

MutablePersona.setPublicencryptionKey(pubEncKey, privSignKey)

Uport.constructor(dappName, opts) ⇒ `Object`

Uport.getUportProvider(rpcUrl) ⇒ `Object`

Uport.getUportProvider() ⇒ `Object`

Uport.getUserPersona() ⇒ `Promise.<MutablePersona>`

Persona.constructor(address, ipfsProvider, web3Provider, [registryAddress]) ⇒ `Object`

Persona.loadAttributes() ⇒ `Promise.<JSON, Error>`

Persona.load(claims) ⇒ `Promise.<JSON, Error>`

Persona.getProfile() ⇒ `JSON`

Persona.getPublicSigningKey() ⇒ `String`

Persona.getPublicEncryptionKey() ⇒ `String`

Persona.getAllClaims() ⇒ `JSON`

Persona.getClaims(attributesName) ⇒ `JSON`

Persona.signAttribute(attribute, privSignKey, issuerId) ⇒ `Object`

Persona.signMultipleAttributes(attribute, privSignKey, issuerId) ⇒ `Array`

Persona.isTokenValid(token) ⇒ `Boolean`

Persona.privateKeyToPublicKey(privateKey) ⇒ `String`

MutablePersona ⇐ `Persona`

MutablePersona.constructor(address, ipfsProvider, web3Provider, [registryAddress]) ⇒ `Object`

MutablePersona.writeToRegistry() ⇒ `Promise.<String, Error>`