lblod-blockchain/README.md

Proof of concept rond Lokale Besluiten als Gelinkte Open Data – centrale vindplaats en mandatendatabank.

# LBLOD
Proof of concept rond Lokale Besluiten als Gelinkte Open Data – centrale vindplaats en mandatendatabank. 


### Repo structure
- __dist__: this contains the transpiled version of the repo
- __src__: this contains the actual code
    - __utils__
        - __api__
            - __apiService__: exposing all services
            - __identityService__: all interactions with identities
            - __queryService__: all interactions with queries
            - __transaction__: all transaction implementations
        - __connection__: class to instantiate a connection
        - __ErrorMessages__: export for all error messages
        - __lblod__: main package exposing all functionalities
        - __wallets__: all possible wallets
    - __index__: exporting of the package



## Features
* Creating a connection to the Rest API
* Publishing a certain asset (Besluit) to the HLF network
* Signing (voting) for a certain asset (Besluit) and register this action on the network
* Validating/Compare an existing asset on the network with a given asset
* Getting a certain asset by asset Id


## Requirements
* [See this page for the requirements of the network - package](https://github.com/VO-Blockchain/LBLOD/tree/master/lblod-network)


# LBLOD Blockchain PoC API References
* [Getting started](#getting-started)
* [LBLOD](#lblod-constructor)
  * [publishBesluit](#publishbesluit)
  * [signBesluit](#signbesluit)
  * [validateBesluit](#validatebesluit)
* [Full implementation example](#full-implementation-example)


## Getting started

First you need to get lblod into your project. This can be done using the following methods:

* npm: `npm install lblod-blockchain`
* bower: `bower install lblod-blockchain`
* meteor: `meteor add vo-blockchain:lblod-blockchain`
* vanilla: link the `dist/index.js`

## LBLOD constructor

###### Parameters
1. `String` - The token to the rest API (Obtained through the network admin)
2. `String` - The baseURL to the Rest API (Obtained through the network admin)
3. `Boolean` - Indicator whether development mode is enabled or not

###### Returns
`LBLOD-Blockchain` instance on which you can call any function specified below.

###### Example
```javascript
import LBLOD from 'lblod-blockchain';

const lblod = new LBLOD('my-api-token', 'api-base-url', false);
```




## publishBesluit

###### Parameters
1. `String` - The id of the besluit (Uri typically)
2. `String` - The besluit which should be hashed (Object must be able to be stringified)

###### Returns
`Promise` - Returns the transactionId of the publication on the blockchain


###### Example
```javascript
import LBLOD from 'lblod-blockchain';

// besluit MUST be processable by a stringifier and should be a JSON file
const myBesluit = besluit.toJSON();

const lblod = new LBLOD('my-api-token', 'api-base-url', false);
const txId = await lblod.publishBesluit('my-besluit-id', myBesluit);
```




## signBesluit

###### Parameters
1. `boolean` - The choice which is made (true = authenticate, false = burn)
2. `String` - The transactionId return from the function "publishBesluit" within this package
3. `String` - The assign signer to perform the action on. Signers are obtained through the wallets export

###### Returns
`Promise` - Returns the transactionId of the sign action on the blockchain


###### Example
```javascript
import LBLOD, { wallets } from 'lblod-blockchain';

// besluit MUST be processable by a stringifier and should be a JSON file
const myBesluit = besluit.toJSON();

// I choose to AUTHENTICATE the asset. True = Authenticate, False = Burn
const myChoice = true;

const lblod = new LBLOD('my-api-token', 'api-base-url', false);
const txId = await lblod.publishBesluit('my-besluit-id', myBesluit);

const result = await lblod.signBesluit(choice, txId, wallets.signer);
```




## validateBesluit

###### Parameters
1. `txId` - The transactionId return from the function "publishBesluit" within this package
2. `String` - The besluit which should be hashed and compared to the original besluit (Object must be able to be stringified)


###### Returns
`Promise` - Returns a promise with True or False depending on the comparing results


###### Example
```javascript
import LBLOD from 'lblod-blockchain';

// besluit MUST be processable by a stringifier and should be a JSON file
const myBesluit = besluit.toJSON();

// fakeBesluit MUST also be processable by a stringifier and should be a JSON file.
// This process should be the EXACT same operations as the process which
// the original published besluit went through to be able to replicate the same hash and result
const myFakeBesluit = fakeBesluit.toJSON();

const lblod = new LBLOD('my-api-token', 'api-base-url', false);
const txId = await lblod.publishBesluit('my-besluit-id', myBesluit);

const result = await lblod.validateBesluit(txId, myFakeBesluit);
console.log('Is myFakeBesluit tampered? ', result);
```







# Full implementation example

This is an example of a service layer in your frontend application which implements all functionalities of this NPM package.

```javascript
import LBLOD, { wallets }  from 'lblod-blockchain';

export default class hlfService {

  constructor(token){
    this.lblod = new LBLOD(token);
  }

  publishBesluit = (besluitId, besluit) => {
    return this.lblod.publishBesluit(besluitId, besluit, wallets.publisher);
  };

  sign = (choice, txId, signer) => {
    return this.lblod.signBesluit(choice, txId, signer);
  };

  validate = (txId, besluit) => {
    return this.lblod.validateBesluit(txId, besluit);
  };

  getAssetById = (txId) => {
    return this.lblod.getBesluitById(txId);
  };
}

```


---
###### Important note
    - This is project is not intended to be used in any production environment as this is a Proof Of Concept and is not ready for production.
    - As identity management is out of the scope of this project, all identities are handled in this package. This is NOT applicable for production and MUST be refactored
    - Error handling is not included in the code examples, but don't forget to implement these with the proper try-catches or when using .then chaining, with .catch