chainmetric-contracts

README

Chainmetric: Smart Contracts

       

Overview

Chainmetric Smart Contracts are designed to grand access to blockchain-stored data while implementing such data validation, aggregation, and management functionality.

Being a part of a permissioned blockchain network based on Hyperledger Fabric stack, such Contracts are written in Go and configured to be deployed as Kubernetes services communicating with each other, blockchain peers, and external applications via gRPC protocol and event streaming.

Requirements

• Deployed Chainmetric network (see network deployment procedure) preferably in Kubernetes environment
• Image registry where chaincode docker images will be hosted (Docker Hub account will do)
• fabnctl command line utility installed on local machine

Contracts reference

Assets contract

Transactions

Transaction	Arguments	Response	Description
Retrieve	id	Asset	Retrieves single record from ledger by a given ID
All	-	[]Asset	Retrieves all records from ledger
Query	AssetsQuery	AssetsResponse	Performs rich query against ledger in search of specific records
Upsert	Asset	id	Inserts new record into the ledger or updates existing one
Transfer	id, holder	-	Changes holder of the specific asset
Remove	Asset	-	Removes record from the ledger by given ID

Example

asset, err := network.GetContract("assets").EvaluateTransaction("Retrieve", id)

Devices contract

Transactions

Transaction	Arguments	Response	Description
Retrieve	id	Device	Retrieves single record from ledger by a given ID
All	-	[]Device	Retrieves all records from ledger
Register	[]Device	id	Creates and registers new device in the blockchain ledger
Update	id, Device	Device	Updates device state in ledger with requested properties
Unbind	id	-	Removes record from the ledger by given ID
Command	DeviceCommandRequest	-	Handles execution requests for devices
SubmitCommandResults	entryID, CommandResultsSubmit	-	Updates command log entry in the ledger
CommandsLog	deviceID	DeviceCommandLogEntry	Retrieves entire commands log from the blockchain ledger

Example

id, err := network.GetContract("devices").EvaluateTransaction("Register", device)

Requirements contact

Transactions

Transaction	Arguments	Response	Description
Retrieve	id	Requirements	Retrieves single record from ledger by a given ID
ForAsset	assetID	[]Requirements	Retrieves all requirements from ledger for specific asset
ForAssets	assetIDs	[]Requirements	Retrieves all requirements from ledger for specific multiply assets
Assign	Requiremnts	id	Assigns requirements to an asset and stores it on the ledger
Revoke	id	-	Revokes requirements from an asset and removes it from the ledger

Example

requirements, err := network.GetContract("requirements").EvaluateTransaction("ForAssets", assetsIDs)

Readings contact

Transactions

Transaction	Arguments	Response	Description
ForAsset	assetID	MetricReadingsResponse	Retrieves all records records from ledger for specific asset
ForMetric	assetID, metricID	MetricReadingsResponse	Retrieves all records records from ledger for specific asset and metric
Post	MetricReadings	id	Inserts new metric readings record into the ledger
BindToEventSocket	assetID, metricID	eventToken	Creates event socket subscription ticket for connected party, so that each posted readings record, which satisfies client request for given asset ID and metric, would be send directly to it via event streaming
CloseEventSocket	eventToken	-	Revokes event socket subscription ticket for connected party

Example

readings, err := network.GetContract("readings").EvaluateTransaction("ForMetric", assetsID, metricID)

Deployment

Chaincodes (alternative to Smart Contracts) in Hyperledger Fabric infrastructure can be deployed both by embedding their source code into the blockchain peers and by deploying them as external services, which is a way more versatile option especially for Kubernetes cluster environment where such Chaincodes can be deployed as a pods.

For chaincodes initial deployment or further updates use deploy cc command as following:

fabnctl deploy cc --arch=arm64 --domain=chainmetric.network --chaincode=assets -C=supply-channel \
   -o=org1 -p=peer0 \
   -o=org2 -p=peer0 \
   -o=org3 -p=peer0 \
   --registry=dockerhubuser ./chaincodes

For more detailed instructions please refer to fabnctl documentation.

Roadmap

• Device remote commands over blockchain events (#1)
• Cache layer for storing contracts operational data e.g. EventSocketSubscriptionTicket (#4)
• Devices location management business logic (#2)
• Requirements violation notification
• Requirements violations rule engine
• Transaction for assets changes history retrieving
• Users contract

Wrap up

Chainmetric's Smart Contracts are the accumulation of this project's business logic in the form of distributed, atomically granulated on-chain services, where each is responsible only for its entities, use cases, and transactions handling.

They are exposing access to the data stored on blockchain immutable ledger by publishing their contracts as gRPC remote procedures and continuously emitted event streams.

Other parts of the Chainmetric project, such as embedded sensor-equipped IoT devices and cross-platform mobile application utilizes exposed contacts by remote procedure calling and subscribing to event streams.

License

Licensed under the Apache 2.0.