What is a uPort identity?

Pelle Braendgaard
Published in
6 min readFeb 27, 2017


In this article I will attempt to cover what you need to know about uPort identities as a developer.

TLDR; At its most basic level, a uPort identity is an Ethereum address. So if all you need when interacting with an end user is their Ethereum address, this is provided by uPort. However, uPort also allows apps and their users to exchange information privately, while still backed by the security of the Ethereum blockchain.

In more detail, a uPort identity is a complete digital representation of a person (or app, organization, device, or bot) that is able to make statements about who they are when interacting with smart contracts and other uPort identities, either on-chain or off-chain. This ability to make statements about themselves, without relying on centralized identity providers, is what makes uPort a platform for self-sovereign identity.

The real power of uPort is that it makes your Ethereum app more approachable to your end users. Some of the interactions enabled by uPort are simple blockchain transactions like buying shares on the Gnosis prediction market, while others include off-chain interactions like making private statements to other uPort users or apps. All of this is possible without your end users having to endure complex key management.

A persistent identity

In traditional public key cryptography systems, public keys represent identities. Identity ownership is determined by possession of the private key that controls the public key. This public/private key model has many beneficial properties that have been used in cryptographic identity systems for years. Not much infrastructure is needed to verify a signature — you just need access to the public key.

This traditional model has a few critical problems though. If you lose your private keys (through loss, theft, or other means), you lose your identity. Furthermore, it is not directly possible to revoke a key without extra centralized infrastructure, nor to securely transfer control of an identity to someone else. These technological limitations have hindered the adoption of previous attempts at cryptographic identity systems.

Ethereum smart contracts provide us with the first general purpose solution to the problem of cryptographic key management, and set the groundwork for persistent identities. An Ethereum identity can be represented by the address of a smart contract or a traditional public key. Since smart contracts can be controlled by other smart contracts, they can be programmed to support various methods of key recovery logic. This flexibility of control logic enabled by Ethereum allows cryptographic identities to become both user friendly and meaningful.

A uPort identity is a very simple smart contract that is controlled by a replaceable controller contract, which contains key recovery and access control logic. The controller contract is in turn controlled by keys stored securely on your smartphone.

In a future article we will explain in detail how this architecture works and the design choices we made for it.

The uPort Registry: A shared source of truth

The uPort Registry is a single smart contract shared by all uPort identities that provides the infrastructure required for off-chain data sharing and verification of identity. Basically, it allows identities to make simple statements about who they are.

If you create a uPort identity within the uPort mobile app, you can set information about yourself to a public profile. By default your name, image, banner image, and description are set to public. In future versions of the app you will be able to control what information is in your public profile, but for now you can think of it as the Ethereum equivalent of your public Facebook profile. This is your public statement to the world about who you are.

The way the uPort App works with the uPort Registry is really simple:

  • It creates a JSON profile object following the http://schema.org conventions
  • The profile JSON is uploaded to IPFS
  • Finally it creates a setAttributes transaction on the Registry, which sets the resulting IPFS hash as a your public statement

Although uPort Registry is a shared contract, the data stored by each identity in this single source of truth is only controllable by the uPort identity itself, making it impossible to censor or block. This simple control aspect is key to the concept of a self-sovereign uPort identity.

It’s important to remember that the uPort Registry contract is a on-chain reference point for off-chain data. The data that is uploaded to IPFS is not stored on-chain, only the IPFS hash is.

The current version of uport-registry is deployed to 0xb9C1598e24650437a3055F7f66AC1820c419a679 on the Ropsten network. Please have a look at the intentionally simple solidity source code.

Case in point, my uPort identity:

My uPort identity is 0xceaaac60d36d2cb52ac727a93ad5ea301afc89dc. Feel free to add me as a contact in your uPort mobile app. You can also look at my identity in a block explorer.

At the time of writing, my current uPort public profile has the IPFS hash QmWBAr1QBWaAGaRJMcggbPiFYTBZhoHc4jBoWtKzLyZfSN

{"@context":"http://schema.org","@type":"Person","name":"Pelle Brændgaard","banner":{"@type":"ImageObject","name":"banner","contentUrl":"/ipfs/QmNXQGZ2kwAqM24pqiibHqrg2JRSUdpnfZohhKjFpM5CNe"},"description":"Lead Engineer on Uport","publicKey":"0x04613bb3a4874d27032618f020614c21cbe4c4e4781687525f6674089f9bd3d6c7f6eb13569053d31715a3ba32e0b791b97922af6387f087d6b5548c06944ab062","image":{"@type":"ImageObject","name":"avatar","contentUrl":"/ipfs/QmZ2F9z9A3cCKe9AREu5XnFE9otKbo4Ptc46A4m3AgY1i9"}}

If you have the uPort mobile app, you can easily view your own public profile by going to Identity Page > Settings > Developer Tools.

On-chain vs Off-chain use

In a pure Ethereum world where all apps and data live completely on the blockchain, we wouldn’t need the uPort Registry as a shared source of truth. Instead, the truth would simply be read from the public blockchain. However, in reality even the simplest dApp UX has a large off-chain data requirement due to blockchain data privacy constraints. If an application UX needs to display any information about a user besides their Ethereum address and balances, developers need to rely on something like the uPort Registry, Facebook Connect, or its own centralized user database.

There are many more advanced use cases for needing to exchange private information, such as annual income or national ID number, between a user and an app. Most people would not be happy storing this information on a public blockchain, and therefore we need a way of sharing it securely off-chain.

A decentralized, on-chain backbone for an off-chain world

As we mentioned earlier, a smart contract identity on the Ethereum blockchain can do almost anything a key-based identity can do, and much more. But unfortunately one thing it cannot do is sign arbitrary off-chain data like a private key can. Therefore we need a way for the uPort Registry to delegate arbitrary off-chain data signing to a keypair.

The publicKey field in the uPort Registry entry serves this purpose. publicKey allows my persistent identity to delegate signing permission to another device, in this case my uPort mobile app. It also also allows me to change this key if I lose or upgrade my device.

The uPort Connect javascript library transparently uses this decentralized public key registry functionality of uPort to securely communicate and share information between your application and our mobile app with JWT (JSON Web Tokens) verified by the uPort Registry.

In a future article we will discuss how you can use uPort Connect to develop additional off-chain features for your users.

Uport humanizes your Ethereum app

Perhaps the most important reason to supporting uPort when building your Ethereum app is that uPort humanizes blockchain user experiences. Users are no longer just abstract hex-encoded addresses interacting with other hex addresses, but real people who are now able to fully express themselves as they interact with other real people, apps, devices and businesses.

In addition, the combination of the uPort mobile app and libraries makes it incredibly easy for you to bring new non-technical users into your apps. We expect this will be a driving force behind the scaling of Ethereum applications into the mainstream.

If you haven’t already done so, please sign up for the uPort closed alpha to receive early access to our app. Next, have a look at our uPort Developer site and join the uPort Gitter channel.



Pelle Braendgaard
Writer for

Engineering Lead for uPort. Opinionated about ethereum, bitcoin, payments and financial services.