uport-lib

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