Digital identity is one of the most exciting emerging use cases for Smart Contracts in blockchain technology.
Traditional identity systems have numerous pain points - they can be insecure and siloed, leaving users with little control over their data. A self-sovereign digital identity puts users back in charge.
In this article, we’ll explore how to build a basic smart contract for managing digital identities on the blockchain. We’ll cover:
- The benefits of a decentralized identity system
- The core architecture for an on-chain identity contract
- Coding the key functions for registering and managing identity credentials
- Example applications like Know Your Customer (KYC) processes
- Challenges and future directions for digital identity
We’ll use Solidity and JavaScript to implement a simple, smart contract that allows users to store and control access to identity attributes like name, address, and date of birth. Even beginners should be able to follow along.
Why Digital Identity Matters
On the web today, we use fragmented, centralized identity management systems. Your identity is essentially chopped up across different silos - your Facebook profile, bank account login, Twitter handle, etc.
These legacy identity systems have many drawbacks:
- Security flaws - Centralized databases are honeypots for hackers. Equifax and other high-profile breaches have exposed millions of identities.
- No user control - You have little control over your data in centralized systems. The platforms own your identity.
- Limited portability - Identities are locked in proprietary silos. This makes it very difficult to bring your identity across platforms.
Blockchain-based decentralized identity solutions address these problems. They allow users to own and control their digital identities fully. Some key principles of self-sovereign identity include:
- Persistent - The identity persists even if a specific company, provider, or network goes away. It does not rely on external authorities.
- Portable - Users should be able to bring their identity with them and transmit it securely across different contexts.
- Privacy-preserving - Selective disclosure allows users to share only certain credentials when needed.
- Consent-based - Sharing of identity details requires explicit user consent.
- Controlled by the user - Users must have full control over their digital identities.
- Easy to use - Systems should have intuitive user experiences.
We can align more closely with these principles with an identity rooted in the blockchain rather than centralized databases. Users will have sovereign control over their personal data and biometrics. Organizations can instantly and securely verify credentials like university degrees, addresses, and birth certificates.
Next, we'll explore how to model digital identity on the blockchain at a high level.
Digital Identity Smart Contract Architecture
Before diving into code, let's outline the key components of a basic identity management smart contract.
At a high level, our contract needs to:
- Allow users to register a new blockchain-based identity
- Enable users to add various credential claims to their identity
- Support revoking credentials that are no longer valid
- Control read access to identity credentials
For simplicity, we will store the actual credential data off-chain. The blockchain will store hashes representing each credential a user has attested.
Here is a diagram for visualizing the architecture:
The contract will store mappings between a user's address and the hashes of their credentials.
The user submits the credential data to an off-chain verification oracle to add a new credential. This could be an accredited university, government agency, or certifying authority that verifies the credential.
The oracle returns a credential hash, which the user can then send to the contract to attach to their identity.
Later, organizations can query the contract for a specific user credential hash. The user can provide the actual plaintext credential data, allowing the organization to verify the hash matches.
Storing the credential hashes rather than plaintext data on-chain helps preserve privacy. The contract will also implement access controls around reading credentials.
Now that we understand the key components at a high level let's start coding our contract!
To follow this tutorial, you must have the following,
Fork the repo here, and let's begin.
Installing Dependencies
We will use Solidity to implement the smart contract itself and JavaScript to write simple tests interacting with it.
First, make sure you have the latest version of Node.js installed. We'll use the Hardhat development environment to compile our Solidity and run tests.
Create a new directory for the project:
mkdir digital-identity
cd digital-identity
Then install Hardhat and Ethers.js:
npm install --save-dev hardhat
npm install --save-dev @nomiclabs/hardhat-ethers ethers
Ethers.js will be useful for writing our tests to call contract functions.
Okay, we're ready to start coding!
Implementing the Smart Contract
Inside the digital-identity directory, create a new file called Identity.sol - this will contain our Solidity smart contract code.
Let's start with some basic boilerplate:
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
contract Identity {
}
This declares the Solidity version and creates the Identity contract shell.
Now, let's define a struct to represent each identity credential. We'll store the hash and a boolean indicating if the credential is revoked:
struct Credential {
bytes32 hash;
bool revoked;
}
Next, we'll define a mapping where the key is a user address, and the value is a mapping of credential types to Credential structs.
mapping (address => mapping (bytes32 => Credential)) public credentials;
This allows us to keep track of all credentials for a particular user, referencing them by a unique bytes32 hash.
The public keyword automatically generates a getter for us to access data in the mapping.
Let's add a function to allow a user to add a new credential:
function addCredential(bytes32 credHash) external {
credentials[msg.sender][credHash] = Credential(credHash, false);
}
Users will call this function and pass in the credential hash they want to add. We add it to their address in the credentials mapping.
Next, let's implement revoking credentials. We'll flip the revoked flag to true in the mapping:
function revokeCredential(bytes32 credHash) external {
Credential storage credential = credentials[msg.sender][credHash];
credential.revoked = true;
}
Reading credentials will require passing in the user's address and the specific credential hash to retrieve. We can implement a simple getCredential function:
function getCredential(address user, bytes32 credHash)
external
view
returns (Credential memory)
{
return credentials[user][credHash];
}
This returns the Credential struct for the specified user and hash. It's marked view so it simply reads state but does not modify it.
That covers the basic functionality! Users can add credentials mapped to their address, revoke them if needed, and read specific credentials by accessing the mapping.
Now, let's write some simple tests to interact with these functions.
Testing the Contract
Hardhat makes testing our contract locally very straightforward.
First, initialize the Hardhat project:
npx hardhat init
This creates a sample Greeter.sol contract we can ignore - our Identity.sol will replace it.
In the hardhat.config.js file, let's add our Solidity compilation config:
solidity: "0.8.0"
Now, create a test directory and add a file TestIdentity.js inside it.
We'll import Hardhat's testing utilities along with ethers and our contract ABI:
const { expect } = require("chai");
const { ethers } = require("hardhat");
const Identity = artifacts.require("Identity");
In our tests, we'll deploy a new instance of the Identity contract and interact with its functions.
For example, to test adding a credential:
it("Should add credential", async function() {
const identity = await Identity.deployed();
const credHash = ethers.utils.formatBytes32String("foo");
await identity.addCredential(credHash);
const credential = await identity.getCredential(owner.address, credHash);
expect(credential.hash).to.equal(credHash);
});
We can test revoking and retrieving credentials in a similar way.
The full suite of tests will validate that:
- Adding credentials store them under the sender's address
- Retrieving a credential returns the correct hash
- Credentials can be revoked by flipping their status
With just these few core functions and tests, we've implemented the basic functionality for managing credentials on-chain!
There are definitely improvements we could make, like access controls on getCredential.
But this covers the core end-to-end workflow. Users can register verifiable credentials on the blockchain and later selectively disclose them to third parties.
Next, explore some sample applications to see the identity contract in action...
Digital Identity Use Cases
Now that we have a basic implementation, what are some real-world use cases for our digital identity smart contract?
Know Your Customer (KYC)
One of the most common applications is using verified identities for KYC and anti-money laundering regulations.
Financial institutions must verify customers' identity before working with them. The traditional KYC process often involves physically inspecting identity documents like passports.
Accredited organizations can verify identity credentials with a digital identity contract like legal name, address, date of birth, etc.
The credentials can be attested with the user's consent and stored in the mapping under their address. Banks or exchanges can instantly verify users by checking their credential hashes on-chain.
This allows near-instant KYC while putting users in charge of sharing their personal data.
Online Services Authentication
Beyond KYC, digital identities open opportunities to improve authentication for online services.
Rather than our identities living in proprietary silos, we can use selective disclosure to prove our identity to any service securely and privately.
Services could request specific credential hashes from users during login or account creation. They can verify the hashes match credentials from trusted issuers without seeing the raw data.
This helps minimize the centralization of identity data and gives users more control.
Verifiable Credentials
Another application is creating verifiable digital credentials - essentially "proof of X" that is checked against the blockchain.
A university could issue verifiable digital diplomas. An employment credential could confer proof of income or employment status. Certifying agencies can create digital certificates for skills, training, and qualifications.
Issuers mint these verifiable credentials by attesting to their validity off-chain, generating a hash, and anchoring that hash to a user's identity in the smart contract mapping.
Any organization can instantly verify a credential hash is associated with the user in a tamperproof way. This creates portable, digital versions of real-world credentials.
Individuals and organizations could take advantage of nearly limitless possibilities for verifiable credentials.
Challenges and Future Work
While identity smart contracts open exciting possibilities, there are still challenges to overcome:
- The credential hashes rely on off-chain oracles for actual verification procedures. Fully decentralized alternatives would be ideal.
- Key management and recovery are hurdles - users must not lose access to their blockchain account and keys.
- User experience still needs improvement for mainstream adoption. Managing keys and hashes is not very user-friendly right now.
- Interoperability with existing identity systems will take time.
- Sybil attacks where an entity spins up multiple fake identities must be mitigated.
- Compliance with evolving regulations will be critical, especially for financial use cases.
Ongoing research is developing solutions in many of these areas. Decentralized identifiers (DIDs) tied to blockchain accounts show promise for simplified identity management.
The world of self-sovereign digital identity is just getting started. As technology matures, decentralized identity systems will likely play a growing role in how we maintain and share our personal data across contexts.
Conclusion
This article covered the benefits of blockchain-based digital identity and how to implement basic smart contract functions like adding credentials and controlling access.
With just Solidity and JavaScript, we built and tested a simple decentralized identity contract. While the contract has room for improvement, it demonstrates core concepts like selective disclosure and self-sovereign data control.
Identity is one of the most compelling emerging use cases for blockchain technology. Self-sovereign identity puts users in charge of their data and identities.
As the space continues to progress, decentralized identity systems will empower people across the globe with financial access, property rights, and safe digital lives.
If you find this post exciting, find more exciting posts on the Learnhub Blog; we write everything tech from Cloud computing to Frontend Dev, Cybersecurity, AI, and Blockchain.
Top comments (3)
Is this not only secure because there's only a hash on the blockchain? Fully decentralizing it would put the contents on the chain and hence publically available - just knowing that a person has an account with bank X is not something that should ever be public. It seems to me this is a blockchain in front of a Web 2 solution, not sure what real benefits it brings over the general concept of a single identity store - although I wouldn't trust many people with all of my security in one place.
Hey, great article. getCredencials method would allow anyone to query any address data. If this method is used to check credentials by thirds, this address should had been granted that party to do it in some way, hadn't it ?
Isn't this only safe since the blockchain only has a hash?