• This repository has been archived on 17/Feb/2021
  • Stars
    star
    100
  • Rank 340,703 (Top 7 %)
  • Language
    JavaScript
  • License
    Apache License 2.0
  • Created over 5 years ago
  • Updated almost 4 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

DID Method implementation using the Sidetree protocol on top of Ethereum and IPFS

See sidetree.js

This repo is no longer maintained.

Element

Build Status codecov

🔥 Experimental Sidetree Protocol based DID Method elem with Ethereum and IPFS

See the DID method specification

See our blog post

[OUTDATED] Click below image for demo video.

Element Testnet Demo

See also ion, sidetree, sidetree-ethereum.

Useful resources

Getting Started

git clone [email protected]:decentralized-identity/element.git
cd element
npm install

Element follows the Mono Repo structure. Running npm install will install dependencies in the top level npm project as well as in the following packages:

  • Element LIB: Javascript SDK for using Element. Works with node 10, node 12 and in the browser
  • Element APP: Progressive Web App to create a wallet, create a DID, add and remove keys, search through the Element Block explorer, etc... The PWA allows you to use two different types of Sidetree nodes:
    • The light node (or browser node) which uses element-lib in the browser for Sidetree operations and interacts with Ethereum through Metamask Make sure you have the Metamask browser extension installed if you want to use it the light node.
    • The full node which uses element-api for Sidetree operations
  • Element API: API powered by element-lib that exposes Sidetree operations with an HTTP interface. See Swagger documentation for more details.

How to use element-lib

cd packages/element-lib

Running the tests

In order to run the tests, you need to start Element services

npm run services:start

This will start 3 services:

  • Ganache: A local Ethereum chain initialized with the Element smart contract running with on port 8545
  • IPFS: A local IPFS node running on port 5001
  • CouchDB: A local CouchDB instance running on port 5984. CouchDB will be ran in the Docker container, so you will need Docker installed. If you don't have it and / or don't want to install it, it is fine. Just be aware that the CouchDB tests will fail

Check that services are properly initalized with

npm run services:healthcheck

Then you can run the tests (note that running this command will initialize the services if they have not been initialized)

npm test

When you are done, you can stop the Element services by running

npm run services:stop

Initializing the Sidetree class

In order to use element-lib in node or in the browser, you will need to initalize the Sidetree class by providing three interfaces:

  • A db interface: this is where all the caching artifacts will be stored. While caching is not technically required for Element to work, CRUD operations will be prohibitively slow without it. To initialize, chose one db adapter (several options are available here):

    • RXDB
    • CouchDB
    • Firestore: A good option if you're going to use Element in a Firebase Cloud Function, pretty slow otherwise. Also note that this technology is proprietary as opposed to the two above which are open source..
  • A storage interface: the Content Addressed Storage layer where Sidetree operation data will be stored. To initialize, chose one storage adapter (several options are available here):

    • IPFS
    • IPFS Storage Manager: A layer on top of IPFS that uses a cache and some retry logic when the call to IPFS fails: This one is recommended for production use as the IPFS link provided by Infura tend to fail intermittently
  • A blockchain interface: An interface for the decentralized ledger to be used for anchoring Sidetree operations. Element may only be used with the Ethereum interface, however feel free to reuse this codebase to implement a did method that uses a different ledger.

  • A parameter object. Currently the supported parameters are:

    • maxOperationsPerBatch: recommended value is 10000,
    • batchingIntervalInSeconds: recommended value is 10,
    • didMethodName: recommended value is did:elem:ropsten for Element testnet
    • logLevel: one of [ error, warn, info, http, verbose, debug, silly ]. error would log all the logs, while silly would only capture the most unimportant ones

See several examples for how to initialize the Sidetree class:

Using element-lib to Create Read Update Delete DIDs

Once you have an instance of the Sidetree class with the suitable adapters, you can access all the helper functions (sidetree.func) and perform CRUD operations (sidetree.op). Here are a few code snippet to get you started:

Create a DID

const { Sidetree, MnemonicKeySystem } = require("@transmute/element-lib");

// Instantiate the Sidetree class
const element = new Sidetree(/* See previous section for how to initialize the Sidetree class*/);

// Generate a simple did document model
const mks = new MnemonicKeySystem(MnemonicKeySystem.generateMnemonic());
const primaryKey = await mks.getKeyForPurpose("primary", 0);
const recoveryKey = await mks.getKeyForPurpose("recovery", 0);
const didDocumentModel = element.op.getDidDocumentModel(
  primaryKey.publicKey,
  recoveryKey.publicKey
);

// Generate Sidetree Create payload
const createPayload = element.op.getCreatePayload(didDocumentModel, primaryKey);

// Create the Sidetree transaction.
// This can potentially take a few minutes if you're not on a local network
const createTransaction = await element.batchScheduler.writeNow(createPayload);
const didUniqueSuffix = element.func.getDidUniqueSuffix(createPayload);
const did = `did:elem:ropsten:${didUniqueSuffix}`;
console.log(`${did} was successfully created`);

Read a DID (aka resolve a DID)

const didDocument = await element.resolve(didUniqueSuffix, true);
console.log(
  `${did} was successfully resolved into ${JSON.stringify(
    didDocument,
    null,
    2
  )}`
);

Update a DID document

Add a new key to the did document

// Get last operation data
const operations = await element.db.readCollection(didUniqueSuffix);
const lastOperation = operations.pop();

// Generate update payload for adding a new key
const newKey = await mks.getKeyForPurpose("primary", 1);
const newPublicKey = {
  id: "#newKey",
  usage: "signing",
  type: "Secp256k1VerificationKey2018",
  publicKeyHex: newKey.publicKey,
};
const updatePayload = await element.op.getUpdatePayloadForAddingAKey(
  lastOperation,
  newPublicKey,
  primaryKey.privateKey
);

// Create the Sidetree transaction.
const updateTransaction = await element.batchScheduler.writeNow(updatePayload);
const newDidDocument = await element.resolve(didUniqueSuffix, true);
console.log(`${JSON.stringify(newDidDocument, null, 2)} has a new publicKey`);

Recover a did document

How to recover a did document using the recovery key if the private key is lost:

// Generate a recovery payload with the inital did document model
const recoveryPayload = await element.op.getRecoverPayload(
  didUniqueSuffix,
  didDocumentModel,
  recoveryKey.privateKey
);

// Send Sidetree transaction
const recoveryTransaction = await element.batchScheduler.writeNow(
  recoveryPayload
);
const recoveredDidDocument = await element.resolve(didUniqueSuffix, true);
console.log(`${JSON.stringify(recoveredDidDocument, null, 2)} was recovered`);

Delete a did document

// Generate a delete payload this will brick the did forever
const deletePayload = await element.op.getDeletePayload(
  didUniqueSuffix,
  recoveryKey.privateKey
);

// Send Sidetree transaction
const deleteTransaction = await element.batchScheduler.writeNow(deletePayload);
const deletedDidDocument = await element.resolve(didUniqueSuffix, true);
console.log(`${JSON.stringify(deletedDidDocument, null, 2)} was deleted`);

How to use element-api

Define the environment file

In the root level directory copy the example config

cp example.env .env

then fill the following values:

  • ELEMENT_MNEMONIC: a mnemonic funded with ethereum. See step 1 and 2 of this tutorial
  • ELEMENT_PROVIDER: either http://localhost:8545 for connecting with local ganache network or use an Infura URL that should look like this https://ropsten.infura.io/v3/<API_TOKEN>
  • ELEMENT_IPFS_MULTIADDR: either /ip4/127.0.0.1/tcp/5001 for connecting with local IPFS node or /dns4/ipfs.infura.io/tcp/5001/https for connecting through Infura
  • ELEMENT_CONTRACT_ADDRESS: "0xD49Da2b7C0A15f6ac5A856f026D68A9B9848D96f"
  • ELEMENT_COUCHDB_REMOTE: Only use this if you want to you the replication feature of CouchDB

Then run the following create the api config file

cd packages/element-api
npm run env:create:prod

You may now start the API by running

npm run start # if you have setup a firebase project
npm run start:standalone # to run the standalone express version of the API

How to use element-app

All config is checked into source so you can run the app by:

npm run start

Useful commands

Install:

npm i

Run smart contract tests:

npm run test:contracts

Run lib, api and app tests:

npm run test

Lint

npm run lint

Coverage

npm run coverage

Publishing

If you have 2fa enabled for npm (and you should!).

lerna version patch
NPM_CONFIG_OTP=123456 lerna publish

Testing Documentation

npm i -g http-server
serve ./docs

See .travis.yml for setup and test commands for linux.

Docker

To run the APP in docker, run

docker run --rm -p 80:80 gjgd/element-app:latest

To run the API in docker, run

docker run --rm -p 80:5002 gjgd/element-api:latest

How to build Element APP with a different domain for the API:

  1. Clone Element
  2. cd packages/element-app
  3. edit the content of .env.production to the API_URL you want to use
  4. docker build -t my-tag .
  5. docker run --rm -p 80:5002 my-tag
  6. Now the app runs on port 80 and will use the API_URL specified in 3)

Release process

lerna publish

More Repositories

1

ion

The Identity Overlay Network (ION) is a DID Method implementation using the Sidetree protocol atop Bitcoin
HTML
1,225
star
2

universal-resolver

Universal Resolver implementation and drivers.
Java
545
star
3

sidetree

Sidetree Specification and Reference Implementation
HTML
438
star
4

decentralized-web-node

Decentralized data storage and message relay for decentralized identity and apps.
HTML
402
star
5

did-jwt

Create and verify DID verifiable JWT's in Javascript
TypeScript
335
star
6

did-resolver

Universal did-resolver for javascript environments
TypeScript
213
star
7

did-jwt-vc

Create and verify W3C Verifiable Credentials and Presentations in JWT format
TypeScript
179
star
8

ethr-did-resolver

DID resolver for Ethereum Addresses with support for key management
TypeScript
168
star
9

didcomm-messaging

JavaScript
163
star
10

github-did

Decentralized Identity with Github
JavaScript
139
star
11

ion-tools

Tools and utilities to make working with the ION network and using ION DIDs easy peasy lemon squeezy
JavaScript
139
star
12

decentralized-identity.github.io

Site for the open source, community-driven group of dev and organizations working toward an interoperable, decentralized identity ecosystem
HTML
98
star
13

interoperability

The archive and information hub for the cross-community interoperability project. Focus is on education and familiarity for various efforts across multiple groups for interoperable decentralized identity infrastructure.
93
star
14

presentation-exchange

Specification that codifies an inter-related pair of data formats for defining proof presentations (Presentation Definition) and subsequent proof submissions (Presentation Submission)
JavaScript
85
star
15

confidential-storage

Confidential Storage Specification and Implementation
TypeScript
80
star
16

bbs-signature

The BBS Signature Scheme
Rust
76
star
17

keri

Key Event Receipt Infrastructure - the spec and implementation of the KERI protocol
HTML
72
star
18

web-did-resolver

DID resolver for HTTPS domains
TypeScript
70
star
19

universal-registrar

Universal Registrar implementation and drivers.
Java
64
star
20

DIDComm-js

JS implementation of pack and unpack
TypeScript
55
star
21

.well-known

Specs and documentation for all DID-related /.well-known resources
HTML
53
star
22

fuzzy-encryption

A variant of a Fuzzy Vault cryptographic scheme designed for encrypting data with better human recovery features.
C++
49
star
23

did-key.rs

Rust implementation of the did:key method
Rust
47
star
24

didcomm-rs

DIDComm messaging specifications implementation: https://identity.foundation/didcomm-messaging/spec/
Rust
46
star
25

keriox

Rust Implementation of the KERI Core Library
Rust
43
star
26

papers

Notes, ideas, and write-ups from DIF members and collaborators
40
star
27

org

DIF docs, wiki, and organizational material
Rich Text Format
39
star
28

did-auth-jose

JOSE-based implementation of DID Authenticated Encryption
TypeScript
39
star
29

did-common-java

Shared DID Java library.
Java
37
star
30

didcomm.org

TypeScript
36
star
31

did-siop

TypeScript
35
star
32

spec-up

Create beautiful, feature-rich technical specifications in markdown
HTML
32
star
33

credential-manifest

Format that normalizes the definition of requirements for the issuance of a credential
JavaScript
30
star
34

ion-sdk

TypeScript SDK for ION
TypeScript
29
star
35

keripy

Python Implementation of the KERI Core Libraries
Python
28
star
36

sidetree-ethereum

Blockchain-specific code for the Sidetree-based DID Method implementation on Ethereum
TypeScript
28
star
37

peer-did-method-spec

A rich DID method that has no blockchain dependencies. The verifiable data registry is a synchronization protocol between peers.
JavaScript
27
star
38

universal-resolver-frontend

Frontend web UI for Universal Resolver.
JavaScript
25
star
39

snark-credentials

25
star
40

identifiers-discovery

Identifiers & Discovery WG operating repo
21
star
41

trustdidweb

Trust DID Web (did:tdw)
18
star
42

waci-presentation-exchange

Wallet And Credential Interactions for Presentation Exchange (Work continues at decentralized-identity/waci-didcomm#1 )
HTML
17
star
43

did-common-dotnet

C#
17
star
44

did-methods

DID Method specs, docs, and materials
17
star
45

hub-node-core

Node.js implementation of the Identity Hub interfaces, business logic, and replication protocol.
TypeScript
17
star
46

lds-ecdsa-secp256k1-2019.js

EcdsaSecp256k1Signature2019 JSON-LD Signature Suite
TypeScript
17
star
47

vc-marketplace

To establish the reference architecture for a Verifiable Credentials Marketplace
HTML
16
star
48

didcomm-bluetooth

a specification that describes discovery and transport over Bluetooth for DIDcomm
16
star
49

horcrux

Horcrux Protocol
16
star
50

kerigo

Go implementation of KERI (Key Event Receipt Infrastructure)
Go
16
star
51

did-security-csharp

C# implementation of DID security and privacy controls
C#
15
star
52

claims-credentials

Claims and Credentials WG operations repo
15
star
53

uni-resolver-driver-did-ccp

A Universal Resolver driver for Baidu did:ccp identifiers.
Java
15
star
54

jwt-vc-presentation-profile

HTML
15
star
55

hub-reference

The official Identity Hub reference implementation bundle for Node.js
JavaScript
15
star
56

c19-vc.com

(DEMO) COVID-19 VC Issuer
JavaScript
14
star
57

didcomm-demo

In browser DIDComm v2 demo.
TypeScript
14
star
58

attestations

Attestation API implementations for various languages and platforms.
JavaScript
14
star
59

hub-sdk-js

JavaScript SDK for interacting with Identity Hubs
TypeScript
14
star
60

wallet-security

Define a common terminology for understanding the security requirements applicable to wallet architectures and wallet-to-wallet and wallet-to-issuer/verifier protocols.
14
star
61

crypto-wg

Meeting notes, transcripts previous agendas and active working group items
13
star
62

edv-spec

Encrypted Data Vault Spec
HTML
13
star
63

veramo-agent-deploy

Generic @veramo/cli agent deployment configuration https://veramo-agent.herokuapp.com
Dockerfile
12
star
64

waci-didcomm

Wallet And Credential Interactions for DIDComm
HTML
12
star
65

agent-explorer

Explore data accross multiple DID agents
TypeScript
12
star
66

uni-resolver-driver-did-ion

Universal Resolver Driver for Identity Overlay Network (ION) DIDs
C#
11
star
67

ion-cli

ION Command Line Interface to make working with the ION network and using ION DIDs easy peasy lemon squeezy
TypeScript
11
star
68

didcomm

11
star
69

did-siop-browser-ext

DID based SIOP
TypeScript
10
star
70

did-registration

A specification for DID create/update/deactivate operations.
HTML
10
star
71

kerijs

JavaScript (nodes) Implementation of the KERI core library.
JavaScript
10
star
72

go-ipfs-ds-azure

Go implementation of ipfs Azure datastore
Go
10
star
73

trust-establishment

https://identity.foundation/trust-establishment
10
star
74

dwn-user-guide

TypeScript
9
star
75

EcdsaSecp256k1RecoverySignature2020

EcdsaSecp256k1RecoverySignature2020
JavaScript
9
star
76

vc-spec-map

Verifiable Credentials Specification Relationship Map
9
star
77

JWS-Test-Suite

JsonWebSignature2020 Test Suite
JavaScript
9
star
78

universal-registrar-frontend

Frontend web UI for Universal Registrar.
JavaScript
8
star
79

presentation-exchange-implementations

Multi-language implementation of the Presentation Exchange protocol.
Go
8
star
80

jsonld-document-loader

TypeScript
8
star
81

wallet-rendering

Specifications for rendering DID and Credential-centric data in wallet applications
JavaScript
8
star
82

jsonld-common-java

Shared JSON-LD Java library.
Java
7
star
83

OpenPgpSignature2019

OpenPgpSignature2019 Linked Data Cryptographic Suite in JavaScript
JavaScript
7
star
84

didcomm-usergroup

DIDComm User Group
7
star
85

wallet-and-credential-interactions

QR Codes and Button for Claiming and Sharing Credentials (and more!)
HTML
7
star
86

schema-directory

A work item of the Claims and Credentials WG at DIF
HTML
7
star
87

did-common-typescript

A common bundle of shared code and modules for working with DIDs, DID Documents, and other DID-related activities
TypeScript
7
star
88

hub-sdk-js-sample

Sample app demonstrating use of the DIF Identity Hub JavaScript SDK.
TypeScript
7
star
89

authentication-wg

6
star
90

presentation-request

Requirements Analysis and Protocol Design for a VC Presentation Request Format
6
star
91

did-crypto-typescript

Crypto library to handle key management for DIDs
TypeScript
6
star
92

universal-wallet-backup-containers

A work Item within the DIF Wallet Security WG aimed to develop a specification for wallet containers
HTML
6
star
93

didcomm-book

5
star
94

universal-resolver-java

5
star
95

did-spec-extensions

Extension parameters, properties, and values for the DID spec registries.
JavaScript
5
star
96

sidetree-reference-impl

Sidetree Reference Implementation
TypeScript
5
star
97

linked-vp

Linked Verifiable Presentation
JavaScript
5
star
98

uni-resolver-driver-dns

A Universal Resolver driver for domain names.
Java
4
star
99

schema-forms

JSON Schema-driven form generator for the input and construction of credentials based on user input
JavaScript
4
star
100

SIG-IoT

DIF IoT Special Interest Group (Open Group)
CSS
4
star