EnGram Amygdala

{width=300}

A strictly typed ORM library for EnGram blockchain. It allows you to use EnGram blockchain as a persistent storage in an organized and model-oriented way without writing custom complex smart contracts.

Note: As transaction fees may be huge, it is strongly advised to only deploy EnGram Amygdala models in testnet or locally using ganache-cli .

Installation

npm i --save @engramnet/amygdala

Setup

const gramAmygdala = require('@engramnet/amygdala');
const path = require('path');
let savePath = path.resolve(__dirname + '/contracts');

const gramAmygdalaProvider = gramAmygdala('http://localhost:8545', savePath);
//engram blockchain provider URL, path to save auto generated smart contracts

const Superhero = gramAmygdalaProvider.createSchema({
    name: "Superhero",
    contractName: "heroContract",
    properties: [{
            name: "name",
            type: "bytes32",
            primaryKey: true
        },
        {
            name: "ability",
            type: "bytes32",
        },
        {
            name: "level",
            type: "uint"
        }
    ]
});

As you can see you can very easily create a new gramAmygdala provider (line 3) by setting only 2 arguments.

1. the URL of the EnGram blockchain provider that you want to use (in the example it is set to a local ganache-cli provider),
2. the path where you want to save the automatically generated smart contracts of your models.

After you create the provider you can create new data schemas using the createSchema() function and pass the schema details in JS object format. Of course you can (an it is advised) keep the schema definitions in separate .JSON files and then import them using the require() statement in the top of your file.

createSchema() returns a Schema object. In order to successfully initialize a Schema object, only one property of the schema definition must have primaryKey field set to true (as shown in the example above) and the type field must be set to one of the legal Solidity data types.

Functions of Schema object

Schema object implements all the functions needed to perform CRUD operations. As all blockchains have an asynchronous nature, all functions in the library return a callback function. After you initialize a Schema, you can call the following functions:

deploy()

It is the fist function that you must call in order to set your model up "up and running". This function generates the solidity Smart contract of your model and it deploys it in the EnGram based blockchain that you have set in the first step. It returns a boolean indicating if the deploy is successfull and an error object that will be undefined if the deploy is successfull. After deploy completes you can call the other functions.

Example:

Superhero.deploy(function (err, success) {
    if (!err) {
        console.log('Deployed successfully');
    }
});

save()

Saves a new record in th blockchain. Make sure to set the primary key field in the object you want to save, otherwise an error will be returned. It returns the saved object and an error object that will be undefined if the object is saved successfully.

Example:

const newHeroObject = {name:'Thor', ability: 'Thunder', wheels: 2};
Superhero.save(newHeroObject, function (err, objectSaved) {
   if (!err) {
       console.log('object saved');
   }
});

find()

Returns all the records of our Schema. Example:

Superhero.find(function (err, allRecords) {
   if (!err) {
       console.log(allRecords);
   }
});

findById()

Returns the record with a specific primary key value if exists. Otherwise it will return an error object mentioning that 'record with this id does not exist'.

Example:

Superhero.findById('Thor', function (err, record) {
   if (!err) {
       console.log(record);
   }
});

deleteById()

Deletes the record with a specific primary key value if exists. Otherwise it will return an error object mentioning that 'record with this id does not exist'.

Example:

Superhero.deleteById('Thor', function (err, success) {
   if (!err) {
       console.log('object deleted successfully');
   }
});

updateById()

Updates the record with a specific primary key value if exists. Otherwise it will return an error object mentioning that 'record with this id does not exist'. It returns the updated record.

The first parameter is the primary key value of the record we want to update. The second parameter is the updated object. Note that is contrary with save() function it is not necessary to set the primary key field and if you do so, it will NOT be updated. If you want to reassign a stored record to a different id you must first delete it and then save a new one with the different primary key value.

Example:

const updatedHeroObject = { ability: 'Storm', wheels: 4 };
Superhero.updateById('Thor', updatedHeroObject, function (err, updatedObject) {
   if (!err) {
       console.log('object updated successfully');
   }
});

setAccount(account)

With this function you can explicitly set the EnGram account that you want to use for the model. If not set, account is set by default to the first account of the provider.

Example project

You can find a detailed and documented example project that implement a REST API for CRUD operations in the EnGram blockchain through EnGram Amygdala models in this Gitlab repo

Tests

You can run tests by typing npm test in the root directory of the library.

License

EnGram Amygdala are licensed under MIT license.