Skip to content

Latest commit

 

History

History
571 lines (445 loc) · 29 KB

DOCS.md

File metadata and controls

571 lines (445 loc) · 29 KB
Raw

Modules

uport-connect/topicFactory

Manages the communication channel between the uport-connect library and a uPort mobile app. The functionality is dependent on the context. If on a desktop device the communication channel is through a server. uPort offers a server called chasqui to implement this, but you may also run you own server. If on a mobile device the communication channel between the broswer and app is managed by passing data with URIs/URLs

Classes

Connect ⇐ ConnectCore

Primary object for frontend interactions with uPort. Bundles all neccesary functionality.

ConnectCore

Primary object for frontend interactions with uPort. ConnectCore excludes some functionality found in Connect for a more customizable and lightweight integration. It does not provide any web3 functionality althought you can still use getProvider to get a provider to use with web3 or other libraries. It removes all default QR injection functionality. Your can choose how you want to handle the UX and/or QR generation and use any QR library you choose. For example, if used in a mobile native app QR generation is not even necessary.

UportSubprovider

A web3 style provider which can easily be wrapped with uPort functionality. Builds on a base provider. Used in Connect to wrap a provider with uPort specific functionality.

uport-connect/topicFactory

Manages the communication channel between the uport-connect library and a uPort mobile app. The functionality is dependent on the context. If on a desktop device the communication channel is through a server. uPort offers a server called chasqui to implement this, but you may also run you own server. If on a mobile device the communication channel between the broswer and app is managed by passing data with URIs/URLs

uport-connect/topicFactory~TopicFactory(isOnMobile, pollingInterval, chasquiUrl) ⇒ function

Returns a function enclosed with the necessary settings which creates topics (or communication channels).

Kind: inner method of uport-connect/topicFactory

Param Type Default Description
isOnMobile Boolean true if in on mobile device, false otherwise
pollingInterval String 2000 the rate at which the messaging server is polled
chasquiUrl String the url of the message server

TopicFactory~waitForHashChange(topicName, cb)

Waits for a window.onhashchange event, which occurs when control is returned from the mobile uPort app to the mobile browser.

Kind: inner method of TopicFactory

Param Type Description
topicName String the topic you are waiting for a response
cb function a callback which receives a response or error

TopicFactory~pollForResult(topicName, url, cb, cancelled)

Polls a given url (messaging server) for given topic response from the mobile uPort app to the mobile browser.

Kind: inner method of TopicFactory

Param Type Description
topicName String the topic you are waiting for a response
url String url to poll for a response
cb function function which is called with a response or error
cancelled function function which returns true if the polling has been cancelled

TopicFactory~clearTopic(url)

Clear a topic on the messaging server, typically used to remove data after a response is received

Kind: inner method of TopicFactory

Param Type Description
url String url endpoint which to clear topic

TopicFactory~newTopic(topicName) ⇒ Promise.<Object, Error>

Creates a topic and random url endpoint on the messaging server. Passes this url in requests to the mobile app. Starts polling for a response from the mobile app at that url. Returns a promise which resolves a response or rejects an error (or timeout).

Kind: inner method of TopicFactory
Returns: Promise.<Object, Error> - a promise which resolves with a response or rejects with an error.

Param Type Description
topicName String the topic you are waiting for a response

Connect ⇐ ConnectCore

Primary object for frontend interactions with uPort. Bundles all neccesary functionality.

Kind: global class
Extends: ConnectCore

new Connect(appName, [opts])

Instantiates a new uPort connect object.

Param Type Default Description
appName String the name of your app
[opts] Object optional parameters
opts.credentials Object pre-configured Credentials object from http://github.com/uport-project/uport-js object. Configure this if you need to create signed requests
opts.signer function signing function which will be used to sign JWT's in the credentials object
opts.clientId String uport identifier for your application this will be used in the default credentials object
[opts.network] Object 'kovan' network config object or string name, ie. { id: '0x1', registry: '0xab5c8051b9a1df1aab0149f8b0630848b7ecabf6', rpcUrl: 'https://mainnet.infura.io' } or 'kovan', 'mainnet', 'ropsten'.
opts.rpcUrl String JSON rpc url (defaults to https://ropsten.infura.io)
opts.infuraApiKey String Infura API Key (register here http://infura.io/register.html)
opts.topicFactory function function which generates topics and deals with requests and response
opts.uriHandler function default function to consume generated URIs for requests, can be used to display QR codes or other custom UX
opts.mobileUriHandler function default function to consume generated URIs for requests on mobile
opts.closeUriHandler function default function called after a request receives a response, can be to close QR codes or other custom UX

Example

import { Connect } from 'uport-connect'
const uPort = new Connect('Mydapp')

connect.getWeb3() ⇒ web3

Instantiates and returns a web3 object wrapped with uPort functionality. For more details see uportSubprovider and getProvider in connectCore.

Kind: instance method of Connect
Returns: web3 - A uPort web3 object

connect.getProvider() ⇒ UportSubprovider

Instantiates and returns a web3 styple provider wrapped with uPort functionality. For more details see uportSubprovider. uPort overrides eth_coinbase and eth_accounts to start a get address flow or to return an already received address. It also overrides eth_sendTransaction to start the send transaction flow to pass the transaction to the uPort app.

Kind: instance method of Connect
Returns: UportSubprovider - A web3 style provider wrapped with uPort functionality

connect.requestCredentials([request], [uriHandler]) ⇒ Promise.<Object, Error>

Creates a request given a request object, will also always return the user's uPort address. Calls given uriHandler with the uri. Returns a promise to wait for the response.

Kind: instance method of Connect
Returns: Promise.<Object, Error> - a promise which resolves with a response object or rejects with an error.

Param Type Default Description
[request] Object {} request object
[request.requested] Array specifies info attributes to request from user, these are non-veried (not attestations) attributes which the user adds themselves to their profile
[request.verfied] Array specifies attestation types to request from user, these are attestations encoded as JWTs. Attestations are verified in this library, you can also use existing JWT libraries for additional support.
[uriHandler] function this.uriHandler function to consume uri, can be used to display QR codes or other custom UX

Example

const req = { requested: ['name', 'country'], verified: ['GithubUser']}
 connect.requestCredentials(req).then(credentials => {
     const address = credentials.address
     const name = credentials.name
     ...
 })

connect.requestAddress([uriHandler]) ⇒ Promise.<String, Error>

Creates a request for only the address of the uPort identity. Calls given uriHandler with the uri. Returns a promise to wait for the response.

Kind: instance method of Connect
Returns: Promise.<String, Error> - a promise which resolves with an address or rejects with an error.

Param Type Default Description
[uriHandler] function this.uriHandler function to consume uri, can be used to display QR codes or other custom UX

connect.attestCredentials(credential, [uriHandler]) ⇒ Promise.<Object, Error>

Consumes a credential object and generates a signed JWT. Creates a request URI with the JWT. Calls given uriHandler with the URI. Returns a promise to wait for the response. Throws error if no signer and/or app identifier is set. Will not always receive a response, response is only a status.

Kind: instance method of Connect
Returns: Promise.<Object, Error> - a promise which resolves with a resonse object or rejects with an error.

Param Type Default Description
credential Object credential object
credential.sub String subject of this credential
credential.claim Object statement(s) which this credential claims, contructed as {key: 'value', ...}
credential.exp String expiry time of this credential
[uriHandler] function this.uriHandler function to consume uri, can be used to display QR codes or other custom UX

Example

const cred = {
   sub: '0xc3245e75d3ecd1e81a9bfb6558b6dafe71e9f347'
   claim: {'email': 'hello@uport.me'}
   exp: '1300819380'
 }
 connect.attestCredentials(cred).then(res => {
   // response okay, received in uPort app
 })

connect.request(request) ⇒ Promise.<Object, Error>

Create a request and returns a promise which resolves the response. This function is primarly is used by more specified functions in this class, which allow you to easily create the URIs and messaging server topics you need here.

Kind: instance method of Connect
Returns: Promise.<Object, Error> - promise which resolves with a response object or rejects with an error.

Param Type Default Description
request Object request object
request.uri String uPort URI
request.topic String messaging server topic object
[request.uriHandler] String this.uriHandler function to consume URI, can be used to display QR codes or other custom UX

connect.contract(abi) ⇒ Object

Builds and returns a contract object which can be used to interact with a given contract. Similar to web3.eth.contract but with promises. Once specifying .at(address) you can call the contract functions with this object. It will create a request, call the uirHandler with the URI, and return a promise which resolves with a transtaction ID.

Kind: instance method of Connect
Returns: Object - contract object

Param Type Default Description
abi Object contract ABI
[request.uriHandler] function this.uriHandler function to consume uri, can be used to display QR codes or other custom UX

connect.sendTransaction(txobj) ⇒ Promise.<Object, Error>

Given a transaction object, similarly defined as the web3 transaction object, it creates a URI which is passes to the uirHandler. It will create request and returns a promise which resolves with the transaction id.

Kind: instance method of Connect
Returns: Promise.<Object, Error> - A promise which resolves with a resonse object or rejects with an error.

Param Type Default Description
txobj Object transaction object, can also be wrapped using addAppParameters
[request.uriHandler] function this.uriHandler function to consume uri, can be used to display QR codes or other custom UX

Example

const txobject = {
   to: '0xc3245e75d3ecd1e81a9bfb6558b6dafe71e9f347',
   value: '0.1',
   function: "setStatus(string 'hello', bytes32 '0xc3245e75d3ecd1e81a9bfb6558b6dafe71e9f347')",
   appName: 'MyDapp'
 }
 connect.sendTransaction(txobject).then(txID => {
   ...
 })

ConnectCore

Primary object for frontend interactions with uPort. ConnectCore excludes some functionality found in Connect for a more customizable and lightweight integration. It does not provide any web3 functionality althought you can still use getProvider to get a provider to use with web3 or other libraries. It removes all default QR injection functionality. Your can choose how you want to handle the UX and/or QR generation and use any QR library you choose. For example, if used in a mobile native app QR generation is not even necessary.

Kind: global class

new ConnectCore(appName, [opts])

Instantiates a new uPort connectCore object.

Param Type Default Description
appName String the name of your app
[opts] Object optional parameters
opts.credentials Object pre-configured Credentials object from http://github.com/uport-project/uport-js object. Configure this if you need to create signed requests
opts.signer function signing function which will be used to sign JWT's in the credentials object
opts.clientId String uport identifier for your application this will be used in the default credentials object
[opts.network] Object 'rinkeby' network config object or string name, ie. { id: '0x1', registry: '0xab5c8051b9a1df1aab0149f8b0630848b7ecabf6', rpcUrl: 'https://mainnet.infura.io' } or 'kovan', 'mainnet', 'ropsten', 'rinkeby'.
opts.infuraApiKey String Infura API Key (register here http://infura.io/register.html)
opts.topicFactory function function which generates topics and deals with requests and response
opts.uriHandler function default function to consume generated URIs for requests, can be used to display QR codes or other custom UX
opts.mobileUriHandler function default function to consume generated URIs for requests on mobile
opts.closeUriHandler function default function called after a request receives a response, can be to close QR codes or other custom UX

Example

import { ConnectCore } from 'uport-connect'
const uPort = new ConnectCore('Mydapp')

connectCore.getProvider() ⇒ UportSubprovider

Instantiates and returns a web3 styple provider wrapped with uPort functionality. For more details see uportSubprovider. uPort overrides eth_coinbase and eth_accounts to start a get address flow or to return an already received address. It also overrides eth_sendTransaction to start the send transaction flow to pass the transaction to the uPort app.

Kind: instance method of ConnectCore
Returns: UportSubprovider - A web3 style provider wrapped with uPort functionality

connectCore.requestCredentials([request], [uriHandler]) ⇒ Promise.<Object, Error>

Creates a request given a request object, will also always return the user's uPort address. Calls given uriHandler with the uri. Returns a promise to wait for the response.

Kind: instance method of ConnectCore
Returns: Promise.<Object, Error> - a promise which resolves with a response object or rejects with an error.

Param Type Default Description
[request] Object {} request object
[request.requested] Array specifies info attributes to request from user, these are non-veried (not attestations) attributes which the user adds themselves to their profile
[request.verfied] Array specifies attestation types to request from user, these are attestations encoded as JWTs. Attestations are verified in this library, you can also use existing JWT libraries for additional support.
[uriHandler] function this.uriHandler function to consume uri, can be used to display QR codes or other custom UX

Example

const req = { requested: ['name', 'country'], verified: ['GithubUser']}
 connect.requestCredentials(req).then(credentials => {
     const address = credentials.address
     const name = credentials.name
     ...
 })

connectCore.requestAddress([uriHandler]) ⇒ Promise.<String, Error>

Creates a request for only the address of the uPort identity. Calls given uriHandler with the uri. Returns a promise to wait for the response.

Kind: instance method of ConnectCore
Returns: Promise.<String, Error> - a promise which resolves with an address or rejects with an error.

Param Type Default Description
[uriHandler] function this.uriHandler function to consume uri, can be used to display QR codes or other custom UX

connectCore.attestCredentials(credential, [uriHandler]) ⇒ Promise.<Object, Error>

Consumes a credential object and generates a signed JWT. Creates a request URI with the JWT. Calls given uriHandler with the URI. Returns a promise to wait for the response. Throws error if no signer and/or app identifier is set. Will not always receive a response, response is only a status.

Kind: instance method of ConnectCore
Returns: Promise.<Object, Error> - a promise which resolves with a resonse object or rejects with an error.

Param Type Default Description
credential Object credential object
credential.sub String subject of this credential
credential.claim Object statement(s) which this credential claims, contructed as {key: 'value', ...}
credential.exp String expiry time of this credential
[uriHandler] function this.uriHandler function to consume uri, can be used to display QR codes or other custom UX

Example

const cred = {
   sub: '0xc3245e75d3ecd1e81a9bfb6558b6dafe71e9f347'
   claim: {'email': 'hello@uport.me'}
   exp: '1300819380'
 }
 connect.attestCredentials(cred).then(res => {
   // response okay, received in uPort app
 })

connectCore.request(request) ⇒ Promise.<Object, Error>

Create a request and returns a promise which resolves the response. This function is primarly is used by more specified functions in this class, which allow you to easily create the URIs and messaging server topics you need here.

Kind: instance method of ConnectCore
Returns: Promise.<Object, Error> - promise which resolves with a response object or rejects with an error.

Param Type Default Description
request Object request object
request.uri String uPort URI
request.topic String messaging server topic object
[request.uriHandler] String this.uriHandler function to consume URI, can be used to display QR codes or other custom UX

connectCore.contract(abi) ⇒ Object

Builds and returns a contract object which can be used to interact with a given contract. Similar to web3.eth.contract but with promises. Once specifying .at(address) you can call the contract functions with this object. It will create a request, call the uirHandler with the URI, and return a promise which resolves with a transtaction ID.

Kind: instance method of ConnectCore
Returns: Object - contract object

Param Type Default Description
abi Object contract ABI
[request.uriHandler] function this.uriHandler function to consume uri, can be used to display QR codes or other custom UX

connectCore.sendTransaction(txobj) ⇒ Promise.<Object, Error>

Given a transaction object, similarly defined as the web3 transaction object, it creates a URI which is passes to the uirHandler. It will create request and returns a promise which resolves with the transaction id.

Kind: instance method of ConnectCore
Returns: Promise.<Object, Error> - A promise which resolves with a resonse object or rejects with an error.

Param Type Default Description
txobj Object transaction object, can also be wrapped using addAppParameters
[request.uriHandler] function this.uriHandler function to consume uri, can be used to display QR codes or other custom UX

Example

const txobject = {
   to: '0xc3245e75d3ecd1e81a9bfb6558b6dafe71e9f347',
   value: '0.1',
   function: "setStatus(string 'hello', bytes32 '0xc3245e75d3ecd1e81a9bfb6558b6dafe71e9f347')",
   appName: 'MyDapp'
 }
 connect.sendTransaction(txobject).then(txID => {
   ...
 })

UportSubprovider

A web3 style provider which can easily be wrapped with uPort functionality. Builds on a base provider. Used in Connect to wrap a provider with uPort specific functionality.

Kind: global class

new UportSubprovider(args)

Instantiates a new wrapped provider

Param Type Description
args Object required arguments
args.requestAddress function function to get the address of a uPort identity.
args.sendTransaction function function to handle passing transaction information to a uPort application
args.provider Object a web3 sytle provider

uportSubprovider.send()

Synchronous functionality not supported

Kind: instance method of UportSubprovider

uportSubprovider.sendAsync(payload, callback)

Overrides sendAsync to caputure the following RPC calls eth_coinbase, eth_accounts, and eth_sendTransaction. All other calls are passed to the based provider. eth_coinbase, eth_accounts will get a uPort identity address with getAddress. While eth_sendTransaction with send transactions to a uPort app with sendTransaction

Kind: instance method of UportSubprovider

Param Type Description
payload Any request payload
callback function called with response or error