ibm-blockchain-js
Advanced tools
Are you looking for the Marbles app demo? That’s not here, head to the marbles example
This is a Node.js library for easier interaction IBM Blockchain chaincode. All documentation is on this page.
Table Of Contents:
npm install ibm-blockchain-js
(example code also provided below)
// The functions below need to exist in your actual chaincode GoLang file(s)
chaincode.query.read(['a'], cb); //will read variable "a" from current chaincode state
chaincode.invoke.write(['a', 'test'], cb); //will write to variable "a"
chaincode.invoke.remove(['a'], cb); //will delete variable "a"
chaincode.invoke.init_marbles([ARGS], cb); //calls my custom chaincode function init_marbles() and passes it ARGS
// Step 1 ==================================
var Ibc1 = require('ibm-blockchain-js');
var ibc = new Ibc1();
var chaincode = {};
// ==================================
// configure ibc-js sdk
// ==================================
var options = {
network:{
peers: [{
"api_host": "xxx.xxx.xxx.xxx",
"api_port": "xxxxx",
"id": "xxxxxx-xxxx-xxx-xxx-xxxxxxxxxxxx_vpx",
"api_url": "http://xxx.xxx.xxx.xxx:xxxxx"
}],
users: [{
"username": "user1",
"secret": "xxxxxxxx"
}],
options: { //this is optional
quiet: true,
timeout: 60000
}
},
chaincode:{
zip_url: 'https://github.com/ibm-blockchain/marbles-chaincode/archive/master.zip',
unzip_dir: 'marbles-chaincode-master/part2_v1.0.0',
git_url: 'https://github.com/ibm-blockchain/marbles-chaincode/part2_v1.0.0'
}
};
// Step 2 ==================================
ibc.load(options, cb_ready);
// Step 3 ==================================
function cb_ready(err, cc){ //response has chaincode functions
app1.setup(ibc, cc);
app2.setup(ibc, cc);
// Step 4 ==================================
if(cc.details.deployed_name === ""){ //decide if I need to deploy or not
cc.deploy('init', ['99'], './cc_summaries', cb_deployed);
}
else{
console.log('chaincode summary file indicates chaincode has been previously deployed');
cb_deployed();
}
}
// Step 5 ==================================
function cb_deployed(err){
console.log('sdk has deployed code and waited');
chaincode.query.read(['a']);
}
The interface to your chaincode functions has changed in v1.0.0 from v0.0.13!
It is only a minor syntax change that should make it more clear to newcomers.
All invocation functions can now be found under chaincode.invoke and all query functions can be found under chaincode.query.
Examples:
query changes - name change
//old code
chaincode.read('a');
//new code
chaincode.query.read(['a']);
invoke changes - name change
//old code
chaincode.init_marble(args);
chaincode.remove(args);
chaincode.write(name, value);
//new code
chaincode.invoke.init_marble(args);
chaincode.invoke.remove(args);
chaincode.invoke.write(args);
deploy changes - added options parameter
//old code
chaincode.deploy('init', ['99'], './cc_summaries', cb_deployed);
//new code
chaincode.deploy('init', ['99'], {save_path: './cc_summaries', delay_ms: 60000}, cb_deployed);
register changes - added new parameter
//old code
ibc.register(i, enrollId, enrollSecret, [callback]);
//new code
ibc.register(i, enrollId, enrollSecret, maxRetry, [callback]);
This is a function that wraps a typical startup using a standard Bluemix IBM Blockchain network.
Take a look at how this function works, especially how it uses the register() function.
If this is not applicable for your network (ie you have a custom IBM Blockchain network) you can easily create your own version of ibc.load() for your needs.
It will run in order:
Options Parameter:
var options = {
network:{
peers: [{
"api_host": "xxx.xxx.xxx.xxx",
"api_port": "xxxxx",
"api_url": "http://xxx.xxx.xxx.xxx:xxxxx"
"id": "xxxxxx-xxxx-xxx-xxx-xxxxxxxxxxxx_vpx",
}],
users: [{
"username": "user1",
"secret": "xxxxxxxx"
}],
options: { //this is optional, gets passed to ibc.network(peers, options);
quiet: true,
timeout: 60000
}
},
chaincode:{
zip_url: 'https://github.com/ibm-blockchain/marbles-chaincode/archive/master.zip', //http/https of a link to download zip
unzip_dir: 'marbles-chaincode-master/part2_v1.0.0', //name/path to folder that contains the chaincode you want to deploy (path relative to unzipped root)
git_url: 'https://github.com/ibm-blockchain/marbles-chaincode/part2_v1.0.0', //git https URL. should point to the desired chaincode repo AND directory
deployed_name: null //[optional] this is the hashed name of a deployed chaincode. if you want to run with chaincode that is already deployed set it now, else it will be set when you deploy with the sdk
}
};
Load the chaincode you want to use.
It will be downloaded and parsed.
The callback will receive (e, obj) where e is the error format and obj is the chaincode object.
"e" is null when there are no errors.
The chaincode object will have dot notation to the functions in the your chaincode.
Example
var options = {
zip_url: 'https://github.com/ibm-blockchain/marbles-chaincode/archive/master.zip', //http/https of a link to download zip
unzip_dir: 'marbles-chaincode-master/part2_v1.0.0', //name/path to folder that contains the chaincode you want to deploy (path relative to unzipped root)
git_url: 'https://github.com/ibm-blockchain/marbles-chaincode/part2_v1.0.0', //git https URL. should point to the desired chaincode repo AND directory
deployed_name: null //[optional] this is the hashed name of a deployed chaincode. if you want to run with chaincode that is already deployed set it now, else it will be set when you deploy with the sdk
};
ibc.load_chaincode(options, cb_ready);
Set the information about the peers in the network.
This should be an array of peer objects.
The optional options parameter should be an object with the field quiet and/or timeout.
true.60000.false will use HTTP instead of HTTPS. Defaults true.
Ex: var peers = [
{
"api_host": "xxx.xxx.xxx.xxx",
"api_port": "xxxxx",
"id": "xxxxxx-xxxx-xxx-xxx-xxxxxxxxxxxx_vpx",
"api_url": "http://xxx.xxx.xxx.xxx:xxxxx"
}
]
ibc.network(peers, {quiet: false, timeout: 120000});
Save the Chaincode Summary File to a path.
Ex:
ibc.save('./');
Clear any loaded chaincode files including the downloaded chaincode repo, and Chaincode Summary File.
Ex:
ibc.clear();
Get statistics on the network's chain.
Ex:
ibc.chain_stats(function(e, stats){
console.log('got some stats', stats);
});
Example Chain Stats:
{
"height": 10,
"currentBlockHash": "n7uMlNMiOSUM8s02cslTRzZQQlVfm8wKT9FtL54o0ywy6BkvPMwSzN5R1tpquvqOwFFHyLSoW44n6rkFyvAsBw==",
"previousBlockHash": "OESGPzacJO2Xc+5PB2zpmYVM8XlrwnEky0L2Ghok9oK1Lr/DWoxuBo2WwBca5zzJGq0fOeRQ7aOHgCjMupfL+Q=="
}
Get statistics on a particular block in the chain.
Ex:
ibc.block_stats(function(e, stats){
console.log('got some stats', stats);
});
Example Block Stats:
{
"transactions": [
{
"type": 3,
"chaincodeID": "EoABNWUzNGJmNWI1MWM1MWZiYzhlMWFmOThkYThhZDg0MGM2OWFjOWM5YTg4ODVlM2U0ZDBlNjNiM2I4MDc0ZWU2NjY2OWFjOTAzNTg4MzE1YTZjOGQ4ODY4M2Y1NjM0MThlMzMwNzQ3ZmVhZmU3ZWYyMGExY2Q1NGZmNzY4NWRhMTk=",
"payload": "CrABCAESgwESgAE1ZTM0YmY1YjUxYzUxZmJjOGUxYWY5OGRhOGFkODQwYzY5YWM5YzlhODg4NWUzZTRkMGU2M2IzYjgwNzRlZTY2NjY5YWM5MDM1ODgzMTVhNmM4ZDg4NjgzZjU2MzQxOGUzMzA3NDdmZWFmZTdlZjIwYTFjZDU0ZmY3Njg1ZGExORomCgtpbml0X21hcmJsZRIHcng2YXRzcBIFZ3JlZW4SAjM1EgNCb2I=",
"uuid": "b3da1d08-19b8-4d8c-a116-b46defb07a7c",
"timestamp": {
"seconds": 1453997627,
"nanos": 856894462
}
}
],
"stateHash": "81ci8IAOeDh0ZwFM6hE/b3SfXt4tnZFemib7sI95cOsNcYMmtRxBWRBA7qnjPOCGU6snBRsFVnAliZXUigQ03w==",
"previousBlockHash": "tpjUh4sgbaUQFO8wm8S8nrm7yCrBa4rphIiujfaYAlEVfzI8IZ0mjYMf+GiOZ6CZRNWPmf+5bekmGIfr0H6zdw==",
"nonHashData": {
"localLedgerCommitTimestamp": {
"seconds": 1453997627,
"nanos": 868868790
}
}
}
The SDK will default to use peer[0]. This function will switch the default peer to another index.
Ex:
ibc.switchPeer(2);
Only applicable on a network with security enabled.
register() will register against peer[peerIndex] with the provided credentials.
If successful, the peer will now use this enrollID to perform any http requests.
ibc.register(3, 'user1', 'xxxxxx', 3, my_cb);
This will call your callback function whenever the block height has changed.
ie. whenever a new block has been written to the chain.
It will also pass you the same response as in chain_stats().
Ex:
ibc.monitor_blockheight(my_callback);
function my_callback(e, chainstats){
console.log('got a new block!', chainstats);
}
Get information about a particular transaction ID.
Ex:
ibc.get_transaction('d30a1445-185f-4853-b4d6-ee7b4dfa5534', function(err, data){
console.log('found trans', err, data);
});
Deploy the chaincode.
Call GoLang function named 'func' and feed it 'args'.
Usually "args" is an array of strings.
The username parameter should be the desired secure context username that has already been registered against the selected peer.
If left null the SDK will use a known username for the selected peer. (this is only relevant in a permissioned network)
Options are
40000Will invoke your Go function CUSTOM_FUNCTION_NAME and pass it args.
Usually args is an array of strings.
The username parameter should be the desired secure context username that has already been registered against the selected peer.
If left null the SDK will use a known username for the selected peer. (this is only relevant in a permissioned network)
Will query your Go function CUSTOM_FUNCTION_NAME and pass it args.
Usually args is an array of strings.
The username parameter should be the desired secure context username that has already been registered against the selected peer.
If left null the SDK will use a known username for the selected peer. (this is only relevant in a permissioned network)
This function is only here to help people transition from ibc v0.0.x to v1.x.x.
You should create your own read() function in your chaincode which will overwrite this prebuilt one.
This function will put the name argument into args[0] and set function to query.
These are passed to the chaincode function Query(stub *shim.ChaincodeStub, function string, args []string).
Read variable named name from chaincode state.
This will call the Query() function in the Go chaincode.
The username parameter should be the desired secure context username that has already been registered against the selected peer.
If left null the SDK will use a known username for the selected peer. (this is only relevant in a permissioned network)
This is the main guy. It is returned in the callback to load_chaincode() and contains all your cc functions + some of the setup/input data.
chaincode =
{
query: {
CUSTOM_FUNCTION_NAME1: function(args, cb){etc...}; //call chaincode function and pass it args
CUSTOM_FUNCTION_NAME2: function(args, cb){etc...};
^^ etc...
}
invoke: {
CUSTOM_FUNCTION_NAME1: function(args, cb){etc...}; //call chaincode function and pass it args
CUSTOM_FUNCTION_NAME2: function(args, cb){etc...};
^^ etc...
}
deploy: function(func, args, path, cb), //deploy loaded chaincode
details:{ //input options get stored here, sometimes its handy
deployed_name: '', //hash of deployed chaincode
func: {
invoke: [], //array of function names found
query: [] //array of function names found
},
git_url: '',
peers: [], //peer list provided in network()
timestamp: 0, //utc unix timestamp in ms of parsing
users: [], //users provided in load()
unzip_dir: '',
zip_url: '',
}
};
{
name: "input error",
code: 400,
details: {msg: "did not provide git_url"}
};
This file is used internally. It is created in ibc.load_chaincode() and updated with chaincode.deploy(). A copy can be saved elsewhere with ibc.save(path). I found it handy in niche cases, but it will probably be unhelpful to most developers.
{
"details": {
"deployed_name": "f6c084c42b3bde90c03f214ac6e0426e3e594807901fb1464287f2c3a18ade717bc495298958287594f81bb0d0cfdd3b4346d438d3b587d4fc73cf78ae8f7dfe",
"func": {
"invoke": ["init", "delete", "write", "init_marble", "set_user", "open_trade", "perform_trade"],
},
{
"query": []
},
"git_url": 'https://github.com/ibm-blockchain/marbles-chaincode/part2_v1.0.0'
"peers": [{
"name": "vp1-xxx.xxx.xxx.xxx",
"api_host": "xxx.xxx.xxx.xxx",
"api_port": "xxx",
"id": "xxxxx_vp1",
"tls": false,
"enrollID": "user1"
}],
"timestamp": 1459779181971,
"users": [{
"enrollId": "user_type1_xxx",
"enrollSecret": "xxx"
}],
"unzip_dir": 'marbles-chaincode-master/part2_v1.0.0',
"zip_url": 'https://github.com/ibm-blockchain/marbles-chaincode/archive/master.zip',
"options": {}
}
}
#FAQ
Correct behavior of ibc.load() is to remove any usernames that do not contain 'type_1' in their name.
This is to conform to the OBC Peer spec of what usernames a dev's app should use.
If this is not applicable for your network (ie you have a custom IBM Blockchain network) you can easily create your own version of ibc.load() for your needs.
I would copy the code found in ibc.load() then modify it to fit your own needs.
Everything important that ibc.load() calls is exposed in this module.
Yes! Head over to the Marbles Node.js Demo
FAQs
A library for easily interacting with IBM Blockchain.
We found that ibm-blockchain-js demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
Socket researchers have discovered malicious npm packages targeting crypto developers, stealing credentials and wallet data using spyware delivered through typosquats of popular cryptographic libraries.
Security News
Socket's package search now displays weekly downloads for npm packages, helping developers quickly assess popularity and make more informed decisions.
Security News
A Stanford study reveals 9.5% of engineers contribute almost nothing, costing tech $90B annually, with remote work fueling the rise of "ghost engineers."