Skip to content

Commit

Permalink
feat(updates): Changes switching usecase from ethr to ezrah
Browse files Browse the repository at this point in the history
  • Loading branch information
@Mozartted
Mozartted committed Nov 14, 2024
1 parent 6002726 commit 728e034
Show file tree
Hide file tree
Showing 9 changed files with 21,234 additions and 543 deletions.
107 changes: 57 additions & 50 deletions docs/guides/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,50 +2,50 @@

## Construct a New Identity

### Create Ethr-DID from scratch
### Create Ezrah-DID from scratch

Creating an Ethr-DID is analogous to creating an Ethereum account, which is an address on the Ethereum blockchain
controlled by a key pair. Your Ethr-DID will be your key pair.
Creating an Ezrah-DID is analogous to creating an Ethereum account, which is an address on the Ethereum blockchain
controlled by a key pair. Your Ezrah-DID will be your key pair.

We provide a convenient method to easily create one `EthrDID.createKeyPair()` which returns an object containing an
We provide a convenient method to easily create one `EzrahDID.createKeyPair()` which returns an object containing an
Ethereum address and private key.

```ts
import { EthrDID } from 'ethr-did'
import { EzrahDID } from 'ezrah-did'

const keypair = EthrDID.createKeyPair()
const ethrDid = new EthrDID({...keypair})
const keypair = EzrahDID.createKeyPair()
const ezrahDid = new EzrahDID({ ...keypair })
// this creates a DID like:
// did:ethr:0x02ac49094591d32a4e2f93f3368da2d7d827e987ce6cdb3bd3b8a3390fde8fc33b
// did:ezrah:0x02ac49094591d32a4e2f93f3368da2d7d827e987ce6cdb3bd3b8a3390fde8fc33b
```

This represents a DID that is based on a secp256k1 key pair (ethereum key pair) and that is anchored on the Ethereum
`mainnet`. As you may have noticed, no transaction was necessary to anchor the DID. This is by design and it is possible
because by default all EthrDIDs resolve to their own public key or ethereum address. Later on we will see how to update
because by default all EzrahDIDs resolve to their own public key or ethereum address. Later on we will see how to update
a DID document, in which case a transaction will be needed.

To create a DID that is anchored on a different network, you must specify a `chainNameOrId` property.

```ts
let chainNameOrId = 'goerli' // you can use the network name for the most popular [test] networks.
const ethrDidOnGoerliNamed = new EthrDID({...keypair, chainNameOrId})
// did:ethr:goerli:0x02ac49094591d32a4e2f93f3368da2d7d827e987ce6cdb3bd3b8a3390fde8fc33b
const ezrahDidOnGoerliNamed = new EzrahDID({ ...keypair, chainNameOrId })
// did:ezrah:goerli:0x02ac49094591d32a4e2f93f3368da2d7d827e987ce6cdb3bd3b8a3390fde8fc33b

chainNameOrId = 5 // goerli chain ID
const ethrDidOnGoerliChainId = new EthrDID({...keypair, chainNameOrId})
// did:ethr:0x5:0x02ac49094591d32a4e2f93f3368da2d7d827e987ce6cdb3bd3b8a3390fde8fc33b
const ezrahDidOnGoerliChainId = new EzrahDID({ ...keypair, chainNameOrId })
// did:ezrah:0x5:0x02ac49094591d32a4e2f93f3368da2d7d827e987ce6cdb3bd3b8a3390fde8fc33b
```

### Use Existing Web3 Provider

If you use a built-in web3 provider like metamask you can use one of your metamask addresses as your identifier.

```typescript
const provider = new Web3Provider((window as any).ethereum);
const provider = new Web3Provider((window as any).ethereum)
const chainNameOrId = (await provider.getNetwork()).chainId
const accounts = await provider.listAccounts()

const ethrDid = new EthrDID({identifier: accounts[0], provider, chainNameOrId})
const ezrahDid = new EzrahDID({ identifier: accounts[0], provider, chainNameOrId })
```

Unfortunately, web3 providers are not directly able to sign data in a way that is compliant with the
Expand All @@ -56,10 +56,10 @@ an attribute to be able to sign JWTs.
You can quickly add one like this:

```js
const { kp, txHash } = await ethrDid.createSigningDelegate() // Adds a signing delegate valid for 1 day
const { kp, txHash } = await ezrahDid.createSigningDelegate() // Adds a signing delegate valid for 1 day
```

This will allow you to use the web3 based EthrDID to sign JWTs using the (unregistered) `ES256K-R` algorithm. To support
This will allow you to use the web3 based EzrahDID to sign JWTs using the (unregistered) `ES256K-R` algorithm. To support
other algorithms, please check out the section on adding attributes below.

#### Note
Expand All @@ -74,50 +74,49 @@ or `privateKey` to the constructor.
### Resolving the DID document

To inspect the corresponding DID document for the DID you just created you can use
the [`ethr-did-resolver`](https://github.com/decentralized-identity/ethr-did-resolver) library. This document is used by
the [`ezrah-did-resolver`](https://github.com/decentralized-identity/ezrah-did-resolver) library. This document is used by
verifiers to check that the signatures issued by your DID match the keys listed for it.

```ts
import { Resolver } from 'did-resolver'
import { getResolver } from 'ethr-did-resolver'
import { getResolver } from 'ezrah-did-resolver'

const rpcUrl = "https://goerli.infura.io/v3/<get a project ID from infura.io>";
const didResolver = new Resolver(getResolver({ rpcUrl, name: "goerli" }));
const rpcUrl = 'https://goerli.infura.io/v3/<get a project ID from infura.io>'
const didResolver = new Resolver(getResolver({ rpcUrl, name: 'goerli' }))

const didDocument = (await didResolver.resolve(ethrDidOnGoerliNamed.did)).didDocument
const didDocument = (await didResolver.resolve(ezrahDidOnGoerliNamed.did)).didDocument

/**
{
"@context": [
"https://www.w3.org/ns/did/v1",
"https://w3id.org/security/suites/secp256k1recovery-2020/v2"
],
"id": "did:ethr:goerli:0x02ac49094591d32a4e2f93f3368da2d7d827e987ce6cdb3bd3b8a3390fde8fc33b",
"id": "did:ezrah:goerli:0x02ac49094591d32a4e2f93f3368da2d7d827e987ce6cdb3bd3b8a3390fde8fc33b",
"verificationMethod": [
{
"id": "did:ethr:goerli:0x02ac49094591d32a4e2f93f3368da2d7d827e987ce6cdb3bd3b8a3390fde8fc33b#controller",
"id": "did:ezrah:goerli:0x02ac49094591d32a4e2f93f3368da2d7d827e987ce6cdb3bd3b8a3390fde8fc33b#controller",
"type": "EcdsaSecp256k1RecoveryMethod2020",
"controller": "did:ethr:goerli:0x02ac49094591d32a4e2f93f3368da2d7d827e987ce6cdb3bd3b8a3390fde8fc33b",
"controller": "did:ezrah:goerli:0x02ac49094591d32a4e2f93f3368da2d7d827e987ce6cdb3bd3b8a3390fde8fc33b",
"blockchainAccountId": "eip155:5:0x80155C25E363Ee9e1BbBCC08cD5Df7CD249A98C4"
},
{
"id": "did:ethr:goerli:0x02ac49094591d32a4e2f93f3368da2d7d827e987ce6cdb3bd3b8a3390fde8fc33b#controllerKey",
"id": "did:ezrah:goerli:0x02ac49094591d32a4e2f93f3368da2d7d827e987ce6cdb3bd3b8a3390fde8fc33b#controllerKey",
"type": "EcdsaSecp256k1VerificationKey2019",
"controller": "did:ethr:goerli:0x02ac49094591d32a4e2f93f3368da2d7d827e987ce6cdb3bd3b8a3390fde8fc33b",
"controller": "did:ezrah:goerli:0x02ac49094591d32a4e2f93f3368da2d7d827e987ce6cdb3bd3b8a3390fde8fc33b",
"publicKeyHex": "0x02ac49094591d32a4e2f93f3368da2d7d827e987ce6cdb3bd3b8a3390fde8fc33b"
}
],
"authentication": [
"did:ethr:goerli:0x02ac49094591d32a4e2f93f3368da2d7d827e987ce6cdb3bd3b8a3390fde8fc33b#controller",
"did:ethr:goerli:0x02ac49094591d32a4e2f93f3368da2d7d827e987ce6cdb3bd3b8a3390fde8fc33b#controllerKey"
"did:ezrah:goerli:0x02ac49094591d32a4e2f93f3368da2d7d827e987ce6cdb3bd3b8a3390fde8fc33b#controller",
"did:ezrah:goerli:0x02ac49094591d32a4e2f93f3368da2d7d827e987ce6cdb3bd3b8a3390fde8fc33b#controllerKey"
],
"assertionMethod": [
"did:ethr:goerli:0x02ac49094591d32a4e2f93f3368da2d7d827e987ce6cdb3bd3b8a3390fde8fc33b#controller",
"did:ethr:goerli:0x02ac49094591d32a4e2f93f3368da2d7d827e987ce6cdb3bd3b8a3390fde8fc33b#controllerKey"
"did:ezrah:goerli:0x02ac49094591d32a4e2f93f3368da2d7d827e987ce6cdb3bd3b8a3390fde8fc33b#controller",
"did:ezrah:goerli:0x02ac49094591d32a4e2f93f3368da2d7d827e987ce6cdb3bd3b8a3390fde8fc33b#controllerKey"
]
}
*/

```

## Exchange verifiable data
Expand All @@ -127,11 +126,11 @@ const didDocument = (await didResolver.resolve(ethrDidOnGoerliNamed.did)).didDoc
A JWT is a JSON object that is signed so it can be verified as being created by a given DID. A JWT looks like this:
`eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NksifQ.eyJpc3MiOiJkaWQ6dXBvcnQ6Mm5RdGlRRzZDZ20xR1lUQmFhS0Fncjc2dVk3aVNleFVrcVgiLCJpYXQiOjE0ODUzMjExMzMsInJlcXVlc3RlZCI6WyJuYW1lIiwicGhvbmUiXX0.1hyeUGRBb-cgvjD5KKbpVJBF4TfDjYxrI8SWRJ-GyrJrNLAxt4MutKMFQyF1k_YkxbVozGJ_4XmgZqNaW4OvCw`

If an `EthrDID` is initialized with a `privateKey` (as it is when creating it from a key pair) then it has the ability
If an `EzrahDID` is initialized with a `privateKey` (as it is when creating it from a key pair) then it has the ability
to sign JWT.

```ts
const helloJWT = await ethrDid.signJWT({hello: 'world'})
const helloJWT = await ezrahDid.signJWT({ hello: 'world' })
```

If you inspect the resulting JWT (you can do that on https://jwt.io or by
Expand All @@ -140,30 +139,30 @@ calling [`did-jwt#decodeJWT()`](https://github.com/decentralized-identity/did-jw

### Verifying a JWT

An `EthrDID` can also verify JWTs that have DIDs as issuers by leveraging the functionality of
An `EzrahDID` can also verify JWTs that have DIDs as issuers by leveraging the functionality of
the [`did-jwt`](https://github.com/decentralized-identity/did-jwt) library.

You will need to use the `didResolver` you just created.

```ts
try {
const { payload, issuer } = await ethrDid.verifyJWT(jwt, didResolver);
const { payload, issuer } = await ezrahDid.verifyJWT(jwt, didResolver)
// `issuer` contains the DID of the signing identity
console.log(issuer)
} catch(e) {
} catch (e) {
console.error('unable to verify JWT: ', e)
}
```

## Manage Keys

The Ethr-DID supports general key management that can be used to change ownership of keys, delegate signing rights
The Ezrah-DID supports general key management that can be used to change ownership of keys, delegate signing rights
temporarily to another account, and update key and service information in its DID document.

### The Concept of Identity Ownership

By default, in ERC1056 an ethereum address (or public key) is owned by itself. This means that creating a DID using
EthrDID is free, as it doesn't involve the sending of transactions.
EzrahDID is free, as it doesn't involve the sending of transactions.

An owner is an address that is able to make and publish changes to the DID. As this is a very important function, you
could change the ownership to use a smart contract based address implementing recovery or multi-sig at some point in the
Expand All @@ -178,14 +177,14 @@ All the following functions assume that the passed in web3 provider can sign Eth

### Changing an Owner

You can change the owner of an Ethr-DID. This is useful in particular if you are changing a provider and want to
You can change the owner of an Ezrah-DID. This is useful in particular if you are changing a provider and want to
continue to use the same identifier.

This creates an Ethereum transaction, which will also broadcast a `DIDOwnerChanged` event. Make sure that the current
account owner has sufficient gas to be able to update it.

```ts
await ethrDid.changeOwner(newOwner)
await ezrahDid.changeOwner(newOwner)
```

Changing the owner to the `null` address means deactivating it (and implicitly revoking all existing keys and services).
Expand All @@ -199,32 +198,32 @@ You can add different delegate types. The two types currently supported
by [DID-JWT](https://github.com/decentralized-identity/did-jwt) are:

- `veriKey` Which adds a `EcdsaSecp256k1RecoveryMethod2020` to the `assertionMethod` section of the DID document
(*Default* for signing general purpose JWTs using `ES256K-R`)
(_Default_ for signing general purpose JWTs using `ES256K-R`)
- `sigAuth` Which adds a `EcdsaSecp256k1RecoveryMethod2020` to the `assertionMethod` and `authentication` sections of
the DID document.

This is useful if you want to give a dApp the permission to sign on your behalf. This creates an Ethereum transaction,
so your current owner account needs sufficient gas to be able to update it.

```ts
await ethrDid.addDelegate(web3.eth.accounts[3])
await ezrahDid.addDelegate(web3.eth.accounts[3])

// Override defaults to expire in 100 days and have ability to authenticate.
await ethrDid.addDelegate(web3.eth.accounts[3], {expiresIn: 8640000, delegateType: 'sigAuth'})
await ezrahDid.addDelegate(web3.eth.accounts[3], { expiresIn: 8640000, delegateType: 'sigAuth' })
```

There also exists a convenience function that creates a new delegate key pair, configures a signer with it and finally
calls the above `addDelegate()` function.

```ts
const {kp, txHash} = await ethrDid.createSigningDelegate('sigAuth', 360)
const { kp, txHash } = await ezrahDid.createSigningDelegate('sigAuth', 360)
```

The `kp` object contains an `address` and `privateKey` attribute. Unless the key is just added temporarily, store it
somewhere safe.

Delegate addresses can be queried both on-chain (
see [`validDelegate()`](https://github.com/uport-project/ethr-did-registry#looking-up-a-delegate)) and off-chain through
see [`validDelegate()`](https://github.com/uport-project/ezrah-did-registry#looking-up-a-delegate)) and off-chain through
the DID document, but they can only represent ethereum addresses, which limits the types of proofs they can produce.
(`ES256K-R` is not a registered algorithm for JWT). For this reason, it is often better to use attributes to add
different types of keys with different capabilities.
Expand All @@ -242,10 +241,18 @@ The following attribute `key` formats are currently support:
By adding an `expiresIn` value, it will automatically expire after a certain time. By default, it expires after one day.

```ts
await ethrDid.setAttribute('did/pub/Secp256k1/sigAuth/hex', '0x034cc8162c28eb201a4b538d6915d08889296a36df34ca76ab2401e804f31cae7a', 31104000)
await ethrDid.setAttribute('did/pub/Ed25519/veriKey/base64', Buffer.from('Arl8MN52fwhM4wgBaO4pMFO6M7I11xFqMmPSnxRQk2tx', 'base64'), 31104000)
await ethrDid.setAttribute('did/svc/HubService', 'https://hubs.uport.me', 10)
await ezrahDid.setAttribute(
'did/pub/Secp256k1/sigAuth/hex',
'0x034cc8162c28eb201a4b538d6915d08889296a36df34ca76ab2401e804f31cae7a',
31104000
)
await ezrahDid.setAttribute(
'did/pub/Ed25519/veriKey/base64',
Buffer.from('Arl8MN52fwhM4wgBaO4pMFO6M7I11xFqMmPSnxRQk2tx', 'base64'),
31104000
)
await ezrahDid.setAttribute('did/svc/HubService', 'https://hubs.uport.me', 10)
```

The [`did:ethr` spec](https://github.com/decentralized-identity/ethr-did-resolver/blob/master/doc/did-method-spec.md)
The [`did:ezrah` spec](https://github.com/decentralized-identity/ezrah-did-resolver/blob/master/doc/did-method-spec.md)
has extensive information on the various attributes you can use.
16 changes: 5 additions & 11 deletions docs/index.md
View file
Original file line number Diff line number Diff line change
@@ -1,14 +1,10 @@
Ethr-DID
========
# Ezrah-DID

A Scalable Identity Method for Ethereum Addresses
-------------------------------------------------
## A Scalable Identity Method for Ethereum (EVM) Addresses

uPort is a self-sovereign digital identity platform---anchored on the Ethereum blockchain. The uPort technology
primarily consists of smart contracts, developer libraries, and a mobile app. uPort identities are fully owned and
controlled by the creator---independent of centralized third-parties for creation, control or validation.
> disclaimer: This version is entirely based off the project by uPort ethr-did. This is an attempt at scaling the functionalities for multiple application across various industries.
Using the Ethr-DID library, you can:
Using the Ezrah-DID library, you can:

- Create and manage keys for DID identities

Expand All @@ -18,9 +14,7 @@ Using the Ethr-DID library, you can:

- Enable discovery of service endpoints (e.g. decentralized identity management services)

See [the guide](./guides/index.md) for more info

The Ethr-DID library conforms to [ERC-1056](https://github.com/ethereum/EIPs/issues/1056) and supports the proposed
The Ezrah-DID library conforms to [ERC-1056](https://github.com/ethereum/EIPs/issues/1056) and supports the proposed
Decentralized Identifiers spec from the W3C Credentials Community Group. These allow for Ethereum addresses and public
keys to be used as fully self-managed Decentralized Identifiers (DIDs), as a result, you can easily create and manage
keys for these identities. This library also allows you to sign standard compliant JSON Web Tokens (JWTs) that can be
Expand Down
Loading

0 comments on commit 728e034

Please sign in to comment.