Deploy Your Chaincode Using the CLI

Once your chaincode project is created, you can deploy it locally to the automatically generated Hyperledger Fabric network, or remotely to your Oracle Blockchain Platform Cloud or Enterprise Edition. You can also package the chaincode project for manual deployment to Oracle Blockchain Platform.

Deploy Your Chaincode to a Local Hyperledger Fabric Network

Once you have created your chaincode project, you can deploy it to a local Hyperledger Fabric network. This single-channel test network is created for you when you install Blockchain App Builder.

The Blockchain App Builder ochain run command starts the Hyperledger Fabric network, other services, and installs and deploys the chaincode for you.

my-mac:GOProject myname$ ochain run -h
Usage: run [options] [...args]
Run chaincode project locally in debug mode.

Arguments :
[...args] (optional) Chaincode instantiate arguments. Arguments should be space separated.

Options:
-h, --help        output command usage information 
-D, --debug       enable debug logging
-P, --debug-port  (optional) specify debug process port
-b, --build       (optional) rebuild runtime if already exists
-p, --project     (optional) Path to Chaincode project to run. If not specified, it defaults to current directory.  

Examples :
$> ochain run

The test network that is created when you install Blockchain App Builder runs Hyperledger Fabric v2.5.7 and Hyperledger Fabric CA v1.5.9.

Token Projects

For token chaincode projects, you must specify a list of admins with the ochain run command:

ochain run <adminList array>

The adminList array is an array of information that specifies the token admins. The adminList array is a mandatory parameter when you deploy a token chaincode project for the first time. If you deploy the project again, you can pass an empty array for the adminList parameter or you can use the adminList parameter to add token admins. Other deployers who are not the first-time deployer must supply an empty array for the adminList parameter. The parameter information is different for fungible tokens and non-fungible tokens:

For fungible tokens that use the Token Taxonomy Framework standard, the parameters are org_id and user_id.
For any tokens that use the ERC-1155 standard, the parameters are orgId and userId.
For non-fungible tokens that use the ERC-721 standard and a TypeScript project, the parameters are orgId and userId.
For non-fungible tokens that use the ERC-721 standard and a Go project, the parameters are OrgId and UserId.

The following examples are for non-fungible tokens.

Example adminList array for TypeScript on Mac OSX and Linux:

'[{"userId":"userid", "orgId":"OrgMSPId"}]'

Example adminList array for Go on Mac OSX and Linux:

'[{"UserId":"userid", "OrgId":"OrgMSPId"}]'

Example adminList array for TypeScript on Microsoft Windows:

"[{\"userId\":\"userid\", \"orgId\":\"OrgMSPId\"}]"

Example adminList array for Go on Microsoft Windows:

"[{\"UserId\":\"userid\", \"OrgId\":\"OrgMSPId\"}]"

For the local Hyperledger Fabric network, the OrgMSPId field is fixed to the value Org1MSP.

If you would like to see the debug logs, you can pass the --debug option to the command. On Windows, use Command Prompt instead of PowerShell if you specify the --debug option. You can run the basic network and deploy the chaincode on a different port from the default by passing the --port option to the command.

Verifying

The following logs show that the chaincode has been installed and deployed successfully.

my-mac:TSProject myname$ ochain run
Recreating orderer.example.com ... done
Recreating ca.example.com ... done
Recreating peer0.org1.example.com ... done
[2020-09-23T18: 04:09.132] [INFO] default -
============ Started Install Chaincode ============
[2020-09-23T18:04:09.193] [INFO] default Chaincode TSProject:l not installed.
[2020-09-23T18:04:09.317] [INFO] default - Successfully sent install Proposal and received ProposalResponse
[2020-09-23T18:04:09.317] [INFO] default - Successfully installed chaincode TSProject
[2020-09-23T18:04:09.317] [INFO] default -
============ Finished Install Chaincode ============
[2020-09-23T18:04:09.317] [INFO] default - Successfully installed chaincode TSProject
[2020-09-23T18:04:09.318] [INFO] default -
============ started instantiate Chaincode ============
[2020-09-23T18:04:09.366] [INFO] default - Successfully sent Proposal and received ProposalResponse
[2020-09-23T18:04:11.434] [INFO] default - The chaincode instantiate transaction has been committed on peer localhost:7051
[2020-09-23T18:04:11.434] [INFO] default - The chaincode instantiate transaction was valid.
[2020-09-23T18:04:11.435] [INFO] default - Successfully sent transaction to the orderer.
[2020-09-23T18:04:11.435] [INFO] default - Successfully instantiated chaincode TSProject on channel mychannel
[2020-09-23T18:04:11.435] [INFO] default - 
============ Finished instantiate Chaincode ============
[2020-09-23T18:04:11.4351 INFO] default - Successfully instantiated chaincode TSProject on channel mychannel 
INFO (Runtime): Chaincode TSProject installed and ready:
INFO (RunCommand): Chaincode TSProject deployed

Troubleshooting

You may encounter the following issues when running your chaincode project on a local network.

Missing Go permissions

While installing Go chaincode project in local network, you might see an error similar to the following:

My-Mac:GoProj myname$ ochain run
Starting ca.example.com    ... done
Starting orderer.example.com ... done
Starting peer0.orgl.example.com ... done
INFO (Runtime): 2020/06/22 22:57:09 build started

INFO (Runtime): Building ....

INFO (Runtime): go build runtime/cgo: copying /Users/myname/Library/Caches/go-build/f8/.….….d: open /usr/local/go/pkg/darwin_amd64/runtine/ 
cgo.a: permission denied

ERROR (Runtime): go build runtine/cgo: copying /Users/myname/Library/Caches/go-build/f8/.….….d: open /usr/local/go/pkg/darwin_amd64/runtime/
cgo.a: permission denied

INFO (Runtime): An error occurred while building: exit status 1

Stopping peer0.orgl.exmple.com ... done 
Stopping ca.example.com	... done
Stopping orderer.example.con ... done

This is due to missing permissions for Go. This error has been seen only in Mac OS. This is a known issue:

Solution: change the permissions of your $GOROOT and try ochain run again:

sudo chmod -R 777 /usr/local/go

Deployment failure

Due to deployment failure, corrupt deployment, Docker peer container full, or Docker peer was killed in local network, you may see an error similar to:

============ Started instantiate Chaincode ============
[2028-19-01T19:25:lO.372] [ERROR] default - Error instantiating Chaincode GollGl on channel mychannel, detailed 
error: Error: error starting container: error starting container: Failed to generate platform-specific docker 
build: Failed to pull hyperledger/fabric-ccenv:latest : API error (404): manifest for hyperledger/ 
fabric-ccenv:latest not found: manifest unknown: manifest unknown [2020-19-01T19:25:10.372] (INFO) default -
============ Finished instantiate Chaincode ============
[2020-19-01119:25:10.372] [ERROR] default - Error: Error instantiating Chaincode Goll01 on channel mychannel, 
detailed error: Error: error starting container: error starting container: Failed to generate platfom-specific 
docker build: Failed to pull hyperledger/fabric-ccenv: latest : API error (404): manifest for hyperledger/ 
fabric-ccenv:lalest not found: manifest unknown: manifest unknown exited: signal: terminated 
INFO: exited: signal: terminated

ERROR: Error in Chaincode deployment

This is due to a peer container not able to start up properly again.

Solution: try the ochain run command again, but with the -b option. This option rebuilds the runtime for you.

ochain run -b

Environment Rebuild Required

Rebuild your environment if you see a channel not found error or an error similar to the following text:

Starting ca.example.com ... 
Starting orderer.example.com ... 
Starting orderer.example.com ... error
ERROR: for orderer.example.com  
Cannot start service orderer.example.com: 
error while creating mount source path '/host_mnt/c/Users/opc/.vscode/extensions/oracle.oracle-blockchain-1.4.0/node_modules/@oracle/ochain-cli/runtime/network/basic-network/config': mkdir /host_mnt/c/Users/opc/.vscode/extensions/oracle.oracle-blockchain-1.4.0: operation not permitted
Starting ca.example.com... error
ERROR: for ca.example.com  
Cannot start service ca.example.com: error while creating mount source path '/host_mnt/c/Users/opc/.vscode/extensions/oracle.oracle-blockchain-1.4.0/node_modules/@oracle/ochain-cli/runtime/network/basic-network/crypto-config/peerOrganizations/org1.example.com/ca': mkdir /host_mnt/c/Users/opc/.vscode/extensions/oracle.oracle-blockchain-1.4.0: operation not permitted
ERROR: for orderer.example.com  
Cannot start service orderer.example.com: error while creating mount source path '/host_mnt/c/Users/opc/.vscode/extensions/oracle.oracle-blockchain-1.4.0/node_modules/@oracle/ochain-cli/runtime/network/basic-network/config': mkdir /host_mnt/c/Users/opc/.vscode/extensions/oracle.oracle-blockchain-1.4.0: operation not permitted
ERROR: for ca.example.com  
Cannot start service ca.example.com: error while creating mount source path '/host_mnt/c/Users/opc/.vscode/extensions/oracle.oracle-blockchain-1.4.0/node_modules/@oracle/ochain-cli/runtime/network/basic-network/crypto-config/peerOrganizations/org1.example.com/ca': mkdir /host_mnt/c/Users/opc/.vscode/extensions/oracle.oracle-blockchain-1.4.0: operation not permitted
Encountered errors while bringing up the project.
ERROR: Starting ca.example.com ... 
Starting orderer.example.com ... 
Starting orderer.example.com ... error
ERROR: for orderer.example.com  
Cannot start service orderer.example.com: error while creating mount source path '/host_mnt/c/Users/opc/.vscode/extensions/oracle.oracle-blockchain-1.4.0/node_modules/@oracle/ochain-cli/runtime/network/basic-network/config': mkdir /host_mnt/c/Users/opc/.vscode/extensions/oracle.oracle-blockchain-1.4.0: operation not permitted
Starting ca.example.com ... error
ERROR: for ca.example.com  
Cannot start service ca.example.com: error while creating mount source path '/host_mnt/c/Users/opc/.vscode/extensions/oracle.oracle-blockchain-1.4.0/node_modules/@oracle/ochain-cli/runtime/network/basic-network/crypto-config/peerOrganizations/org1.example.com/ca': mkdir /host_mnt/c/Users/opc/.vscode/extensions/oracle.oracle-blockchain-1.4.0: operation not permitted
ERROR: for orderer.example.com  
Cannot start service orderer.example.com: error while creating mount source path '/host_mnt/c/Users/opc/.vscode/extensions/oracle.oracle-blockchain-1.4.0/node_modules/@oracle/ochain-cli/runtime/network/basic-network/config': mkdir /host_mnt/c/Users/opc/.vscode/extensions/oracle.oracle-blockchain-1.4.0: operation not permitted
ERROR: for ca.example.com  
Cannot start service ca.example.com: error while creating mount source path '/host_mnt/c/Users/opc/.vscode/extensions/oracle.oracle-blockchain-1.4.0/node_modules/@oracle/ochain-cli/runtime/network/basic-network/crypto-config/peerOrganizations/org1.example.com/ca': mkdir /host_mnt/c/Users/opc/.vscode/extensions/oracle.oracle-blockchain-1.4.0: operation not permitted
Encountered errors while bringing up the project.
ERROR: Error in Chaincode deployment

To rebuild your local environment, run the following command:

ochain run -b

Deploy Your Chaincode to a Remote Oracle Blockchain Platform Network

After you've deployed and tested your chaincode project on a local network to ensure it's working as designed, you can deploy it to Oracle Blockchain Platform.

Deploy Your Chaincode

Usage: ochain deploy [options] [...args]

The following arguments and options can be used with the ochain deploy command:

my-mac:TSProject myname$ ochain deploy -h 
Usage: deploy [options] [...args]
Deploy chaincode project to Oracle Blockchain Platform

Arguments:
     [...args]    (optional) Chaincode instantiate arguments. Arguments should be space separated.
 
Options :
    -h, --help                      output command usage information
    -D, --debug                     enable debug logging
    -P, --project <project>         (optional) Path to Chaincode project to deploy. If not specified, it defaults to current directory.
    -c, --channel <channel>         (optional) Blockchain Channel to deploy chaincode to. If not specified, it defaults to the 'default' channel.
    -u, --username <username>       (required) A user name that has install chaincode privileges. Contact your administrator for more details.
    -v, --userversion <userversion> (optional) A user-specified chaincode version.
                             If a version isn't specified, for a new chaincode it will start at v1 and then increment to v2, v3, and so on.
                             For an existing chaincode, v1.a will increment to v1.a1, v1 will increment to v2, and v1.0 will increment to v1.1.
    -s --sign <password>            (required) Password to authenticate user.
    -r, --url <url>                 (required) Restproxy Url of the remote OBP instance.
    For example,
    OBP Cloud Services: https://test-xyz-abc.blockchain.ocp.oraclecloud.com:7443/restproxy
    OBP Enterprise Edition: https://restproxy.test-xyz-abc.blockchain.platform.com:443/restproxy

Examples:
$> ochain deploy -u <username> -s <password> -r <REST proxy URL of the remote instance> -c <name of the channel>

Enter the Oracle Identity Cloud Service user name and password for an Oracle Blockchain Platform user with the ADMIN or REST_CLIENT roles. For more information about users and roles, see Set Up Users and Application Roles in Administering Oracle Blockchain Platform Enterprise Edition.

To invoke the chaincode, only the REST_CLIENT role is necessary. To deploy or upgrade the chaincode, the IDCS user must also be assigned the ADMIN role.

After the chaincode has successfully deployed to the remote Oracle Blockchain Platform, the log will show that the following events occurred:

Oracle Blockchain Platform details were successfully fetched.
The list of peers was successfully fetched.
The chaincode project was successfully installed.
The chaincode project was successfully approved and committed.
The chaincode was successfully deployed on each peer and the channel.

In an environment with multiple organizations, to re-deploy the chaincode on the same channel through a participant instance, use the console to deploy the chaincode.

Upgrading the Chaincode Project

Upgrading the chaincode is handled automatically by Blockchain App Builder. After you make changes to your chaincode, call the ochain deploy command again, which will automatically upgrade the project for you. When you run the ochain deploy command again, specify an empty array for the adminList parameter or use the adminList parameter to add token admins. If you are not the first-time deployer, you must supply an empty array for the adminList parameter.

If your upgrade is successful, the log will show that the following events occurred:

Oracle Blockchain Platform details were successfully fetched.
The list of peers was successfully fetched.
A check was made to determine if the chaincode project is already installed, and if so, the version was fetched.
The chaincode version was successfully upgraded (for example, from version 1.0 to 2.0).

In an environment with multiple organizations, to upgrade the chaincode, use the console and manually approve the chaincode from the participants.

Package Your Chaincode Project for Manual Deployment to Oracle Blockchain Platform

You can package your chaincode projects for manual deployment to Oracle Blockchain Platform Cloud or Enterprise Edition.

Usage: ochain package

The package command creates an archive file that contains only the build and distribution files. The binary, libs, node_modules, and test folders from your chaincode project are not included. This archive file can be manually uploaded to Oracle Blockchain Platform for deployment.

Because of changes to software prerequisites, when you run the ochain package command for TypeScript chaincode, you are prompted for the provisioning date of the Oracle Blockchain Platform instance that you want to create the package for. The TypeScript chaincode created in Blockchain App Builder is not compatible with previous versions of Oracle Blockchain Platform without changes to the underlying infrastructure. Blockchain App Builder packages the chaincode infrastructure accordingly based on your selection.

my-mac:~ myname$ ochain package -h 
Usage: package [options]
Package and archive an Ochain chaincode project 
Options :
    -h, --help             output command usage information
    -D, --debug            enable debug logging
    -p, --project <path>   Path to the Ochain chaincode project to be packaged. If not specified, it defaults to current directory.
    -o, --out <path>       Path to the generated chaincode archive file. If not specified, it defaults to current directory.
About:
This CLI command packages and archives an existing chaincode project 
Examples:
$> ochain package --project <Path to the Ochain chaicode project> —out <Path to the generated chaincode archive file>

When the command completes successfully, the location of the package is returned.

This command takes two optional arguments:

--project
This option defines the location of the Blockchain App Builder chaincode project to package. If not specified, the location defaults to the current directory.
--out
This option can be used to give the output path of the generated archive file. If not specified, it defaults to the current directory.

Example:

ochain package -p /Blockchain/DevTools/bp1/CC -o /Blockchain/DevTools/bp1/output

"Your chaincode project has been packaged at /Blockchain/DevTools/bp1/output/CC.zip"