Skip to content

Commit

Permalink
docs: update README template and add quick start documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@whitneypurdum
whitneypurdum committed Apr 29, 2022
1 parent b9919e1 commit 25b85c9
Showing 1 changed file with 151 additions and 27 deletions.
178 changes: 151 additions & 27 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,34 +1,28 @@
<p align="center">
<img src="https://github.com/energywebfoundation/iam-client-lib/actions/workflows/deploy.yml/badge.svg" />
<a href="https://www.energyweb.org" target="blank"><img src="./docs/images/EnergyWeb_logo.png" width="120" alt="Energy Web Foundation Logo" /></a>
</p>

# Identity and Access Management (IAM) Client Library

TypeScript library to be used within decentralized applications for authentication and authorization using DIDs (Decentralized Identifiers) and VCs (Verifiable Credentials)
## Overview
IAM Client Library is a [TypeScript](https://www.typescriptlang.org/) library to be used in decentralized applications for authentication and authorization using [Decentralized Identifiers (DIDs)](https://www.w3.org/TR/did-core/) and [Verifiable Credentials (VCs)](https://www.w3.org/TR/vc-data-model/). DIDs and VCs are central components of self-sovereign identity, a paradigm that promotes user custody over their digital identity.

##
To read more about Decentralized Identifiers and Verifiable Credentials, and how they are used in the Energy Web tech stack, see our documentation [here](https://energy-web-foundation.gitbook.io/energy-web/foundational-concepts/self-sovereign-identity).

![IAM-client-lib demos](screenshots/react-angular-vue_demos.png)
`iam-client-lib` is a key dependency of [Switchboard](https://switchboard.energyweb.org/welcome), the identity and access management (IAM) interface for the [Energy Web Decentralized Operating System](#ew-dos).

## Live Demos
Using `iam-client-lib`, Switchboard allows users to:

[![react logo](examples/react-icon.png) React Demo](https://did-auth-demo.energyweb.org/react-example/) / [![angular logo](examples/angular-icon.png) Angular Demo](https://did-auth-demo.energyweb.org/angular-example/) / [![vue logo](examples/vue-icon.png) Vue Demo](https://did-auth-demo.energyweb.org/vue-example/)

Demo source code: [iam-client-examples](https://github.com/energywebfoundation/iam-client-examples)

## Documentation

[Read the Docs](https://energy-web-foundation-iam-client-lib.readthedocs-hosted.com/)

## [Getting Started](docs/Quick_start.md)
- Create self-sovereign Decentralized Identifiers (DID) for users and assets using a connection with a crypto wallet such as MetaMask. DIDs are anchored in a smart contract on the Energh Web Chain
- Define hierarchical, role-based structures for [organizations](./docs/guides/organization.md), [applications](./docs/guides/application.md) and [assets](./docs/guides/asset.md) that participate in grid activities
- Request and issue Verifiable Credentials that are required to take on roles within an organization or application that is registered on Switchboard

## Development

For testing use `npm run test:watch`
The following is for installing and building `iam-client-lib` directly.
For guidance on how to integrate the library into an application, see [**Getting Started**](#getting-started) below.

### Installing Dependencies

Using `npm` to install dependencies:
Use `npm` >= 7 to install dependencies.

```sh
npm install ./energyweb-km-utils-v1.0.0.tgz
Expand All @@ -42,29 +36,159 @@ npm install ./energyweb-km-crypto-v1.0.0.tgz
npm install
```

### Compile & Build
### Compile and Build
To generate bundled JS files and types, use `npm run build`. Generated files are located in the dist folder.

### Testing
Tests are located in the /e2e directory. For testing, use `npm run test:watch`.

## Getting Started
The following is for integrating `iam-client-lib` as a dependency in your application.

### Demo Source Code
See source code examples for integrating `iam-client-lib` into client applications here: [iam-client-examples](https://github.com/energywebfoundation/iam-client-examples)

[![react logo](examples/react-icon.png) React Demo](https://did-auth-demo.energyweb.org/react-example/) / [![angular logo](examples/angular-icon.png) Angular Demo](https://did-auth-demo.energyweb.org/angular-example/) / [![vue logo](examples/vue-icon.png) Vue Demo](https://did-auth-demo.energyweb.org/vue-example/)

### Pre-requisites

- `iam-client-lib` is written in TypeScript. Your application must use Node.js >= 10
- `iam-client-lib` has a [WebAssembly](https://webassembly.org/) dependency. Some frameworks/bundlers do not support this out of the box, so additional action is required based on the framework you are using:

**For Angular applications**, add the following to `package.json`:

``
"browser": {
"fs": false,
"os": false,
"path": false
}
``

To generate bundled JS files and types, use the following command. Generated files are located in the **_dist_** folder.
**For React applications:** you must add a `wasm-loader` to your Webpack configuration. If you do not have direct access to your webpack config, you can use [@craco/craco](https://www.npmjs.com/package/@craco/craco) or [react-app-rewired](https://www.npmjs.com/package/react-app-rewired).

### Install
To install the latest version of `iam-client-lib`:

```sh
npm i iam-client-lib
```

To install the pre-realse version of `iam-client-lib`:
```sh
npm run build
npm i iam-client-lib@canary
```

Note that some library dependencies require `node.js` built-ins. When `iam-client-lib` is used in browser applications, you must make sure these dependencies are [polyfilled](https://developer.mozilla.org/en-US/docs/Glossary/Polyfill). If your application is bundled with Webpack, most dependencies can be polyfilled with [node-polyfill-webpack-plugin](https://www.npmjs.com/package/node-polyfill-webpack-plugin).

### Initialization
**Note:** You can see a full implementation of initializing `iam-client-lib` in the Switchboard application [here](https://github.com/energywebfoundation/switchboard-dapp/blob/develop/src/app/shared/services/iam.service.ts).

Your application will need to initialize the library's modules. Because the library's modules have internal depenencies, modules must be initialized by the application in the correct order:

#### 1. Initialize signer service
This will initialize staking and messaging services, and allow a connection to the cache server.

```js
const { signerService, messagingService, connectToCacheServer } =
await initWithPrivateKeySigner(privateKey, rpcUrl);
```

#### 2. Connect to the cache server.
Depending on the signer type (i.e. MetaMask, WalletConnect), a signature may be requested.

```js
// IAM has builtin default settings for VOLTA CHAIN, which can overriden
// 1111 is an example of another ChainID (https://chainlist.org/)
setChainConfig(1111, {
didContractAddress: '0x3e2fb24edc3536d655720280b427c91bcb55f3d6',
ensRegistryAddress: '0xa372d665f83197a63bbe633ebe19c7bfd4943003',
ensResolverAddress: '0xe878bdcf5148307378043bfd2b584909aa48a227',
rpcUrl: 'http://some-rpc.com',
});

setMessagingConfig(1111, {
messagingMethod: MessagingMethod.Nats,
natsServerUrl: 'https://some-exchange-server.com',
});

setCacheConfig(1111, {
url: 'https://some-cache-server.com/',
cacheServerSupportsAuth: true,
});

const {
cacheClient,
domainsService,
connectToDidRegistry,
verifiableCredentialsService,
} = await connectToCacheServer();
```

## Active Maintainers
#### 3. Connect to the DID registry
```js
const { didRegistry, claimsService } = await connectToDidRegistry();
```

## Documentation
For further documentation on `iam-client-lib` modules and API:
- [ReadTheDocs](https://energy-web-foundation-iam-client-lib.readthedocs-hosted.com/)

## Contributing Guidelines
Please read [CONTRIBUTING.md](https://gist.github.com/PurpleBooth/b24679402957c63ec426) for details on our code of conduct, and the process for submitting pull requests to us.

## Questions and Support
For questions and support please use Energy Web's [Discord channel](https://discord.com/channels/706103009205288990/843970822254362664)

Or reach out to our contributing team members:

- [John Henderson](https://github.com/jrhender)
- [Dmitry Fesenko](https://github.com/JGiter)
- [Jakub Sydor](https://github.com/Harasz)
- [Ashish Tripathi](https://github.com/nichonien)

## Contributing

Please read [CONTRIBUTING.md](https://gist.github.com/PurpleBooth/b24679402957c63ec426) for details on our code of conduct, and the process for submitting pull requests to us.
## EW-DOS
The Energy Web Decentralized Operating System is a blockchain-based, multi-layer digital infrastructure.

## License
The purpose of EW-DOS is to develop and deploy an open and decentralized digital operating system for the energy sector in support of a low-carbon, customer-centric energy future.

We develop blockchain technology, full-stack applications and middleware packages that facilitate participation of Distributed Energy Resources on the grid, and create open market places for transparent and efficient renewable energy trading.

- To learn about more about the EW-DOS tech stack, see our [documentation](https://app.gitbook.com/@energy-web-foundation/s/energy-web/).

- For an overview of the energy-sector challenges our use cases address, go [here](https://app.gitbook.com/@energy-web-foundation/s/energy-web/our-mission).

For a deep-dive into the motivation and methodology behind our technical solutions, we encourage you to read our White Papers:

- [Energy Web White Paper on Vision and Purpose](https://www.energyweb.org/reports/EWDOS-Vision-Purpose/)
- [Energy Web White Paper on Technology Detail](https://www.energyweb.org/wp-content/uploads/2020/06/EnergyWeb-EWDOS-PART2-TechnologyDetail-202006-vFinal.pdf)


## Connect with Energy Web
- [Twitter](https://twitter.com/energywebx)
- [Discord](https://discord.com/channels/706103009205288990/843970822254362664)
- [Telegram](https://t.me/energyweb)

## License
This project is licensed under the GNU General Public License v3.0 or later - see the [LICENSE](LICENSE) file for details

## FAQ

Frequently asked questions and their answers will be collected here.


















0 comments on commit 25b85c9

Please sign in to comment.