Skip to content

gkapkowski/uport-lib

BranchesTags

Repository files navigation

uport uport chat

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

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

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.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

About

Main uPort library

Resources

Readme

License

Apache-2.0 license
Activity

Stars

2 stars

Watchers

3 watching

Forks

18 forks
Report repository

Releases

1 tags

Packages

No packages published

Languages