Preparing your apps for our new Standards based Identity Architecture

Published in

uPort

5 min readJul 30, 2018

TLDR; We are rolling out a new identity architecture in the next release of our mobile app that will be released by August 15th (we previously said August 7th). If you use uport-connect or uport npm modules you will need to update to uport-connect@0.7.5 or uport@0.6.3 respectively. If you use the address returned by requestCredentials for creating ethereum transactions, use networkAddress instead.

If you‘ve been following our Github Project over the last 6 months you will have noticed a lot of work happening behind the scenes. We have completely redesigned our Identity architecture based on our experiences over the last three years.

The Decentralized Identity world itself has also matured, with the first proper industry standards solidifying in the Decentralized Identifier Spec.

We are actively working actively with the Decentralized Identity Foundation, W3C Verifiable Claims Working Group and of course the Ethereum Communities ERC Process on this.

Our next architecture is based on the Decentralized Identifier Spec and the ERC1056 Lightweight Ethereum Identity spec, which brings in a large number of benefits for both you as developers and your end users.

Much simpler on-boarding of your users

The most obvious benefit to your users is that it is now much easier to create an identity and connect it to your app. After downloading the uPort app, they should be able to open it, create a new Identity and login to your app in less than a minute.

Our previous approach was both slow, expensive and often error-prone due to network congestion issues — as it included 2 Ethereum Transactions just to register.

Due to this we had to limit spam registrations by verifying a users phone number. Verifying phone numbers is a surprisingly error prone process adding both UX and support issues between you and your users. Many privacy concerned individuals were also rightly concerned about why we were asking for their phone number.

Now creating a new Identity is as easy as creating an Ethereum Key Pair. This also means we can provide, much better automated key management for your users.

Identities versus Accounts

We now distinguish between an identity and an account. Your identity is now an identifier for identifying yourself and your users in off-chain transactions.

An identity address following the DID standard is prefixed with did:. Ours are prefixed with did:ethr: for new identities and did:uport: for older existing identities. Example DIDs looks like this:

did:ethr:0xf3beac30c498d9e26865f34fcaa57dbb935b0d74
did:uport:2nQtiQG6Cgm1GYTBaaKAgr76uY7iSexUkqX

As a developer, you should treat the DID (Identity Address) as opaque. This means you should use this as the user ID in your app and you should NOT use the embedded address in any Ethereum transaction.

Mainnet Identities

All identities are now created on the Ethereum Mainnet. What does created mean? Since Identity Creation is now the same as an Ethereum Account creation a transaction is no longer needed for creation.

What does created on Mainnet mean then? The Ethereum Identity Registry deployed on Mainnet is used to register any changes to key ownership in the future. So signature verification is always verified by looking up the authorized signing key on the Mainnet.

Mainnet Ethereum Accounts

You can now request a Mainnet account by configuring your uPort Connect object like this:

Ethereum Account funding

On testnets we previously had automated account funding. This was very simple for onboarding new test users. We are now removing this for new accounts, since it introduced more complexity and proprietary functionality to uPort. Your existing test users on test nets will continue to have support for this, but it is now deprecated.

We are continuing our work with the Ethereum community on automated gas funding and have open sourced our Sensui account funding service.

Since gas funding is now handled by users, we now also have improved display of gas cost on the transaction request card. We are continuing to improve this process in the future.

Gas cost is now shown on transaction card

Increased on-chain privacy

For most non-technical users the idea that all blockchain transactions are public is very difficult to understand.

It is even more confusing that you can use the same Ethereum address for multiple dApps, making it very easy to inadvertently share your CryptoKitty or Token balances while playing on VirtuePoker or bidding on a gig at GitCoin.

By default, we now create a new account for each app a user interacts with, which significantly increases the privacy of users by not mixing Ethereum accounts.

Now an account will by default be used only by your application. The address for this account is now returned in the networkAddress field. If you use our built in Web3 provider this is automatic.

For future requests to your app this same account will always be returned by default.

Update your libraries to the new minor releases

As a developer with an existing dApp using uport-connect update to uport-connect@0.7.5. See Release v0.7.5 Required Upgrade to support new uPort Clients for more info and a possible minor change you may have to do in your code.

If you have an existing app using the uport npm module, update it to uport@0.6.3. See Release v0.6.3 Required Upgrade to support new uPort Clients

We have attempted to make these libraries fully backwards compatible, so in most cases you do not need to do any further changes. If you were using the address field for Ethereum transactions, you should change your code to use networkAddress instead.

Warning about a coming full library refactoring

We have learnt a lot from developers over the last two years and are working on refactoring of our primary libraries.

These will be breaking changes, but they are the result of feedback from many of you guys. They also fully support many of the new features of our new Identity Architecture.

These newly refactored libraries should be ready sometime in August, but they are available both on GitHub and as pre-release npm packages now.

If you are interested please see these PR’s. Feel free to start experimenting with it, but we will likely have more breaking changes.

Stay posted for in depth articles about these in August.