@energyweb/origin-247-certificate v3.4.1-alpha.1647862965.0

Origin 24/7 SDK - Certificate module

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 section.

It is advised to go through whole README carefully

Specific requirements

Despite typical 24/7 SDK requirements and setup, you will need

• Redis (For enqueueing we use bull package)
• Peer runtime dependencies: yarn add @energyweb/issuer

Installation

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

0. Add peer runtime dependencies: yarn add @energyweb/issuer
1. For NestJS Bull please consult: https://docs.nestjs.com/techniques/queues and setup BullModule.forRoot.

Usage

Import Certificate module into one of your applications modules:

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

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

Use the service:

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;
}

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 unnecesary to do blockchain seeding migrations. How to use:

• import certificate module into one of your applications modules
• at application bootstrap, use OnChainCertificateFacade.deploy() method

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

constructor(
   private onChangeCertificateFacade: OnChainCertificateFacade
) {}

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

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

Notes

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

Testing

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 regular installation instructions described above.
1. You need to import OffChainCertificateEntities entities, and add them to TypeORM.forRoot
2. You need to run migrations from origin-247-certificate, e.g.

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

3. 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 OffChainCertificateService methods not available in on-chain version:

• issueWithTxHash
• claimWithTxHash
• transferWithTxHash
• batchIssueWithTxHash
• batchClaimWithTxHash
• batchTransferWithTxHash

They trigger regular methods under the hood, except that they return transaction hash alongside of regular return value.

Testing

Just as with OnChain module, you can import OffChainCertificateForUnitTestsModule.