Commerce-chain NPM

Blockchain Ecommerce module

The ecommerce blockchain interface allows interacting with the blockchain via an interface.

#####Definitions:

wallet and account refer to the same thing, and can be used interchangeably
gas: is a representation of computing power used to perform some action. Actions which require gas are actions such as deploying a new contract, or altering any data on the contract. The normal 'getters' do not use gas if they are pure (i.e. the simple getters where absolutely no more processing is done than saying return localVariable)

Requirements:

NodeJS - install the (latest) NodeJS for your Operating System.
Ganache (as a local blockchain provider) - https://github.com/trufflesuite/ganache/releases/download/v2.0.1/Ganache-2.0.1-setup.exe

##Features:

Store all you contracts in the contract/ folder. All contracts here will be compiled into a JSon file and stored in the build/ when completed. Each contract is store with the following format: ${contract-name}.sol
Accounts are managed by the interface. You can set the account you wish to use in the configuration file app_config.json, or the interface can manually create an account on the first run. This will require user interaction.
An account topup feature is included. The account/wallet address and password can also be stored in the configuration file app_config.json

Configuration

The configuration file has the following JSon format:

{
  "secret": {
    "private_key": "",
    "password": ""
  },
  "wallet": {
    "address": "",
    "unlockDuration": "30"
  },
  "topUp": {
    "address": "",
    "password": "",
    "enable": "true",
    "amount": "20"
  },
  "provider": {
    "protocol": "ws",
    "address": "0.0.0.0",
    "method": "",
    "port": "8545",
    "usesWebsocket": "true"
  },
  "contract": {
    "contractName": "ContractName",
    "deployAddress": "",
    "deployGas": "6000000",
    "transactionGas": "3000000"
  },
  "debug": "yes"
}

Secret

This is where the wallet/account you are using for deploying the contract (which becomes the contract owner) is saved.

private_key: this is the wallet/account's private key
password: this is the wallet/account's password

Note: do not give this info out to anyone. Also, make a backup of this. If you lose this, you cannot recover it, and any published contracts will become useless

Wallet

The wallet contains information which can be publicly available.

address: the wallet address (aka public address) which everyone can and will see when a transaction is completed by this wallet.
unlockDuration: when a transaction is sent to the blockchain, to add or update a field(s) on the blockchain or even to transfer funds from one account to another or to a contract, the account needs to be unlocked. This time is in seconds.

####TopUp Topup is used to ensure that the wallet that is being used for all the transactions does not run out of funds. If it does, then a transaction from the topup wallet is done to ensure continued use of the application.

address: public/wallet address
password: password of wallet to unlock wallet, it is lock immediately after transferring funds.
enable: enable the ability to topup
amount: the topup amount on each topup instance

Note: if you ever get a message like Account does not exist. This means in the provider you are using, the account (topup wallet most likely) does not exist. In future, support (can/will) be added.

Provider

The provider is the means of communicating with the blockchain. The blockchain can be a public blockchain used by all such as testrpc, Rinkby, or mainnet, or a local blockchain such as Ganache.

usesWebsocket: true if using the websocket provider (preferred over http), or false if using not using web sockets
protocol: protocol used to connect to the network. Suggested to use WebSockets provider ws, as using Http providerhttp will prevent the use of events.
address: the ip address or domain of the provider
port: port used by provider
method: if using a public provider, you may be required be given an API key, which is secret. The format for the extension or method call for each provider may be different.

e.g. wss://infura.com:12345/api/user?token=12345657890
     ^_^   ^________^ ^___^^_________________________^ 
 protocol    domain    port       method

e.g. ws://0.0.0.0:8545
     ^_^^________^^__^ 
 protocol   ip    port

Note: If fields are missing such as method for a localhost ganache session, leave them blank in the configuration file

Contract

This stores information about the contract and deployment/utilization options

contractName: the name of the contract you wish to deploy. This is the actual contract name as specified in the contract implementation (and the file name of the compiled contract in the build/ folder).
deployGas: gas used to deploy contract. Leave this at about 6000000. The unused gas is returned.
transactionGas: gas used when performing a state-altering transaction (or money transfer).
deployAddress: the address where the contract is going to be deployed.

ote: if you wish to redeploy the contract, clear this field to make it blank. Alternatively, if you wish to reconnect to an old contract, place the contract deployed address in here. This assumes the web interface is compatible with the contract.

How To Use:

###1. Import: Import the blockchain module (assuming it is the current module folder) with

const _contractInterface = require('./interface');      // used to interact with contract
const _web3Helper = require('./web3-helper');           // helper functions and utilies

###2. Initialize Blockchain Initialize the contract which compiles all contracts, creates/imports/access account to deploy contract from, and finally deploy or acquire the contract

_contractInterface.init(callback);

###3. Get instance Get contract instance.

const blockchain = _contractInterface.getContractInterface()

###4. Start using blockchain

###4.1 Events Subscribe to an event. Currently, only one event callback is supported. This can however be extended using the EventEmitter. This is left to custom implementations.

_contractInterface.subscribeToEvent(_contractInterface.EventType, callback)

Unsubscribe to an event

_contractInterface.unsubscribeToEvent(_contractInterface.EventType)

Note: see EventType for a list of all events ###4.2 Call Functions Call functions on contract:

contractInterface.getCategoryLength(callback)

Functions

getCategoryLength: number of categories
getProductsLength: number of products
getTransactionLength: number of transactions
getSuppliersLength: number of suppliers
getPurchasesLength: number of purchases per transaction
getPurchasesIndex: index of all purchases per transaction
getTransactionIndex: index of all tranasctions
getProductIndex: index of all products
getSuppliersIndex: index of all suppliers
getCategoryIndex: index of all categories
getTransaction: get a transaction object
getPurchase: get a purchase object
getProduct: get a product object
getSupplier: get a supplier object
getCategory: get a category object
checkTransactionExists: checks if a transaction exists
checkPurchaseExists: checks if a purchase from a transction exists
checkProductExists: checks if a product exists
checkSupplierExists: checks if a supplier exists
checkCategoryExists: checks if a category exists
getAllTransactions: get all transactions on blockchain
getAllPurchases: get all purchases per transactions on blockchain
getAllProducts: get all products on blockchain
getAllSuppliers: get all suppliers on blockchain
getAllCategories: get all categories on blockchain
setTransaction: update a transaction
setPurchase: update a purchase of transaction
setProduct: update a product
setSupplier: update a supplier
setCategory: update a category
addTransaction: add a transaction
addPurchase: add a purchase
addProduct: add a product
addSupplier: add a supplier
addCategory: add a category
updateTransactionStatus: updates a transaction's status
refundTransaction: refund a transaction (beta)
returnedPurchase: return items from a purchase (beta)
setEnableSupplierViewAllTransactions: enable all suppliers to view all transactions, or only transactions where they are part of in terms of their products being purchased