sidetree.js
SeeThis repo is no longer maintained.
Element
elem
with Ethereum and IPFS
π₯ Experimental Sidetree Protocol based DID Method See the DID method specification
See our blog post
[OUTDATED] Click below image for demo video.
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, whilesilly
would only capture the most unimportant ones
See several examples for how to initialize the Sidetree class:
- For a local node used for testing purposes : uses RXDB for in memory cache, local IPFS node for the storage interface, and local Ethereum node for the blockchain interface
- For a production node running in nodeJS: uses Firestore for the cache, IPFS Storage Manager for the storage interface, and Infura Ropsten for the blockchain interface
- For a production node running in the browser: uses RXDB for in browser cache, IPFS Storage Manager for the storage interface and Metamask for the blockchain interface
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 thishttps://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:
- Clone Element
cd packages/element-app
- edit the content of
.env.production
to the API_URL you want to use docker build -t my-tag .
docker run --rm -p 80:5002 my-tag
- Now the app runs on port 80 and will use the API_URL specified in 3)
Release process
lerna publish