# @energyweb/origin-247-certificate

Latest version **4.1.5** (published 2023-03-06) · 0 weekly downloads

## Install

```sh
npm install @energyweb/origin-247-certificate
pnpm add @energyweb/origin-247-certificate
yarn add @energyweb/origin-247-certificate
bun add @energyweb/origin-247-certificate
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.1.5 |
| Published | 2023-03-06 |
| First published | 2021-07-01 |
| Weekly downloads | 0 |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 10 |
| Unpacked size | 403.1 KB |
| Known vulnerabilities | 0 (+8 in 4 direct dependencies) |
| Install scripts | no |
| Maintainers | kyleiankian, energywebdev, aznagy, bagaric, pkosin, drgorb, kroy, manihagh |

## Links

- npm: https://www.npmjs.com/package/@energyweb/origin-247-certificate
- npm.io page: https://npm.io/package/@energyweb/origin-247-certificate

## Dependencies (10)

- [pg](https://npm.io/package/pg.md) 8.7.1
- [bull](https://npm.io/package/bull.md) 3.29.3
- [ethers](https://npm.io/package/ethers.md) 5.3.1
- [lodash](https://npm.io/package/lodash.md) 4.17.21
- [typeorm](https://npm.io/package/typeorm.md) 0.2.41
- [passport](https://npm.io/package/passport.md) 0.5.0
- [class-validator](https://npm.io/package/class-validator.md) 0.13.2
- [reflect-metadata](https://npm.io/package/reflect-metadata.md) 0.1.13
- [class-transformer](https://npm.io/package/class-transformer.md) 0.4.0
- [cache-manager-ioredis](https://npm.io/package/cache-manager-ioredis.md) 2.1.0

## Recent versions

- 4.1.5 (latest) — 2023-03-06
- 4.0.1-alpha.1648721260.0 (canary) — 2022-03-31
- 4.1.4 — 2023-03-06
- 4.1.3 — 2023-03-03
- 4.1.2 — 2023-02-23
- 4.1.1 — 2023-02-23
- 4.1.0 — 2022-07-29
- 4.0.1-alpha.1648714301.0 — 2022-03-31
- 4.0.0 — 2022-03-23
- 3.4.1-alpha.1647949312.0 — 2022-03-22
- 3.4.1-alpha.1647942193.0 — 2022-03-22
- 3.4.1-alpha.1647885052.0 — 2022-03-21
- 3.4.1-alpha.1647862965.0 — 2022-03-21
- 3.4.1-alpha.1647860993.0 — 2022-03-21
- 3.4.1-alpha.1647509998.0 — 2022-03-17
- … 61 more at https://npm.io/package/@energyweb/origin-247-certificate/versions

## README

<p align="center">
  <a href="https://www.energyweb.org" target="blank"><img src="./energyweb.png" width="120" alt="Energy Web Foundation" /></a>
</p>

# Origin 24/7 SDK - Certificate module

## Description

Certificate module (and its `OnChainCertificateService`) allow to deploy contracts; issue, transfer and claim certificates.

It enqueues and batches transactions, which is required for optimal blockchain work.

It also exposes off-chain implementation, that stores everything in local database, and (on request) synchronizes
everything to blockchain. This implementation is described in [OffChain Module](#offchain-module) section.

**It is advised to go through whole README carefully**

## Requirements

-   Nest.js application (`origin-247-certificate` is Nest.js module)
-   TypeORM configured
-   Redis (for enqueueing we use [bull](https://github.com/OptimalBits/bull) package)

## Installation

\*\*If you were redirected here from `origin-247-claim` or `origin-247-transfer` modules,
please apply [OffChain Module](#offchain-module) section installation (and usage (manual blockchain synchronization in particular)) as well.

0. Add peer runtime dependencies: `yarn add @energyweb/issuer`
1. Setup `BullModule.forRoot` as described in Nest.js documentation: https://docs.nestjs.com/techniques/queues
2. Install `@energyweb/origin-247-certificate`
3. Add `OnChainCertificateEntities` to your `TypeORM.forRoot` entities.
4. You need to run migrations from `origin-247-certificate`, e.g.

```
"typeorm:run:certificate": "node_modules/typeorm/cli.js migration:run --config node_modules/@energyweb/origin-247-certificate/dist/js/ormconfig.js",
```

## OnChainCertificateModule

Make sure you have [certificates deployed](#deploying-and-migrating-contracts)

Import Certificate module into one of your applications modules:

```ts
import { OnChainCertificateModule } from '@energyweb/origin-247-certificate';

@Module({
    imports: [OnChainCertificateModule]
})
export class SomeModule {}
```

Use the service:

```ts
import { OnChainCertificateService, ONCHAIN_CERTIFICATE_SERVICE_TOKEN } from '@energyweb/origin-247-certificate';

/**
 * Because certificate entity allows to store custom data called "metadata"
 * user can provide typing for metadata.
 *
 * See README metadata section for more information.
 */
interface IMetadata {
  myCustomCertificateData: string;
}

@Injectable()
export class SomeService {
  constructor(
    @Inject(ONCHAIN_CERTIFICATE_SERVICE_TOKEN)
    private certificateService: OnChainCertificateService<IMetadata>
  ) {}

  public async issueRandomCertificate(): Promise<void> {
    await this.certificateService.issue({
      ...
    });
  }
}
```

### Deploying and migrating contracts

It is possible to deploy contracts using `OnChainCertificateFacade`. When using this method, it is unnecessary to do blockchain seeding migrations.

How to use:

0. Configure environment variables: `ISSUER_PRIVATE_KEY` (key for deployer), `WEB3` (RPC address)
1. Import certificate module into one of your applications modules
2. At application bootstrap, use `OnChainCertificateFacade.deploy()` method

```ts
import { OnChainCertificateFacade } from '@energyweb/origin-247-certificate';
// ...
const appModule = AppModule.register();
const app = await NestFactory.create(appModule);
const blockchainFacade = await app.resolve<OnChainCertificateFacade>(OnChainCertificateFacade);
await blockchainFacade.deploy();
```

or

```ts
import { OnChainCertificateFacade } from '@energyweb/origin-247-certificate';

@Module({
    imports: [OnChainCertificateModule]
})
export class AppModule {
    constructor(private onChangeCertificateFacade: OnChainCertificateFacade) {}

    public async onApplicationBootstrap() {
        await this.onChangeCertificateFacade.deploy();
    }
}
```

### Testing modules that import OnChainCertificateModule

Use `OnChainCertificateForUnitTestsModule` (instead of regular module) which abstracts away whole `issuer`, blockchain, database and Redis dependencies. This implementation stores certificates in memory. It is not bullet-proof (because it's really simple), but should handle most happy-paths.

## OffChain Module

OffChain module allows to store everything in local database (therefore making any changes immediate),
and then on-request to synchronize it with a blockchain (internally it uses `OnChainCertificateModule` for that).

### Installation

0. Apply `OnChainCertificateModule` installation instructions described above.
1. You need to import `OffChainCertificateEntities` entities, and add them to `TypeORM.forRoot`
2. Import `OffChainCertificateModule` wherever you want to use `OffChainCertificateService` or `BlockchainSynchronizationService`.

### Usage

`OffChainCertificateService` exposes interface extending on-chain version.
The main difference is the returned certificate interface. It returns _read model_, which is off-chain representation.

It has two fields: `internalCertificateId: number` and `blockchainCertificateId: number | null` instead of one `certificateId`. `internalCertificateId` is used for any communication through `OffChainCertificateService`. But if you want to find certificate in `OnChainCertificateService` you need to use `blockchainCertificateId` which is it's on-chain id. `blockchainCertificateId` can be null if it was not synchronized yet.

**Synchronization doesn't happen automatically.** You need to manually call `BlockchainSynchronizationService.synchronize` in your application. This gives you the flexibility to synchronize everything in cron or manually after some set of events happen.

Off-chain implementation performs few retries if _persisting_ events on blockchain fails (e.g. due to network problems)

## Additional resources

### Unit tests

If you want to unit test module, that imports `OnChainCertificateModule` or `OffChainCertificateModule`, you can import `OnChainCertificateModule` or `OffChainCertificateModule` instead.
They abstract away all dependencies (database, Redis, and others). These modules are not bullet-proof, but should be sufficient for testing most paths.

### Metadata

Each certificate is able to store _metadata_ information, which is used for storing
custom payloads.

Therefore all certificate types (including service) imported from the module give user the ability to provide interface/type for that metadata (as generic type). This way metadata stays typed across application. It's best to create this type somewhere and reuse it across application.

Metadata is serialized internally via `JSON.stringify` therefore metadata **has to** be serializable.
Any value accepted by `JSON.stringify` can be used as metadata (including null - which is default value for metadata field)

### Environment configuration

| Variable name                     | Default value    | Description                                                                                                                      |
| --------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `CERTIFICATE_QUEUE_LOCK_DURATION` | 240 \* 1000 [ms] | How long processor can lock given queue item before marking it stale (stalled queue items are rerun again) - change with caution |
| `CERTIFICATE_QUEUE_DELAY`         | 10 \* 1000 [ms]  | How long each queue item should wait before finishing it's processing - helps with some transaction nonce problems               |
| `BLOCKCHAIN_POLLING_INTERVAL`     | 4000 [ms]        | How often blockchain should be polled for new events                                                                             |
| `ISSUER_PRIVATE_KEY`              | none             | Issuer private key used for deploying certificates                                                                               |
| `WEB3`                            | none             | RPC address - separate addresses with `;` to add fallback RPC                                                                    |

### Notes

1. If one item of batch fails, then whole batch fails.

## Questions and Support

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

Or reach out to us via email: 247enquiries@energyweb.org

## EW-DOS

The Energy Web Decentralized Operating System is a blockchain-based, multi-layer digital infrastructure.

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)

---
_Source: https://npm.io/package/@energyweb/origin-247-certificate · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
