Skip to main content

Chaincode Deployment Guide

This guide walks you through the complete process of deploying chaincode to your FireFly stack, from packaging to registration and testing.

Prerequisites

Before proceeding, ensure you have:

Overview​

The deployment process consists of four main steps:

  1. Package - Bundle your chaincode into a deployable format
  2. Deploy - Upload the package to the Fabric network
  3. Define Interface - Create a contract interface in FireFly
  4. Register API - Register the chaincode as a callable API

Step 1: Package the Chaincode​

First, navigate to the package chaincode directory:

cd chaincodes/package

Create Core Configuration File​

Create an empty core.yaml file:

touch core.yaml
Why an Empty core.yaml?

FireFly requires this file for the packaging process to work correctly with the Hyperledger Fabric peer CLI. For more details, see the FireFly Documentation.

Install Dependencies and Package​

Install the chaincode dependencies and create the package:

# Install npm dependencies
npm install

# Build chaincode
npm run package

# Package the chaincode
peer lifecycle chaincode package \
  --lang node \
  -p . \
  --label pm3package_X.Y \
  ./pm3package.zip

Replace X.Y with your desired version number (e.g., 1.0, 1.1, 2.0).

Example for version 1.0:

peer lifecycle chaincode package \
  --lang node \
  -p . \
  --label pm3package_1.0 \
  ./pm3package.zip
Version Numbering

Use semantic versioning (MAJOR.MINOR) for your chaincode:

  • MAJOR: Incompatible API changes
  • MINOR: Backward-compatible functionality additions

Example: 1.0, 1.1, 2.0, 2.1

Verify Package Creation​

Check that the package was created successfully:

ls -lh pm3package.zip

You should see the pm3package.zip file in your current directory.

Step 2: Deploy to FireFly Network​

Deploy the packaged chaincode to your FireFly stack using the FireFly CLI:

ff deploy fabric dev ./pm3package.zip firefly pm3package X.Y

Parameters explained:

  • dev - Your stack name
  • pm3package.zip - The package file you created
  • firefly - The channel name
  • pm3package - The chaincode name
  • X.Y - The version number (must match the version used in packaging)

Example for version 1.0:

ff deploy fabric dev pm3package.zip firefly pm3package 1.0
Version Consistency

Ensure the version number (X.Y) matches exactly what you used when packaging the chaincode in Step 1.

Verify Deployment​

The deployment process will:

  1. Install the chaincode on all peer nodes
  2. Approve the chaincode for all organizations
  3. Commit the chaincode definition to the channel

Watch the output for any errors. A successful deployment will show approval and commitment messages for all organizations.

Step 3: Define Contract Interface​

Now you need to define the contract interface in FireFly so it knows how to interact with your chaincode.

Get the Interface Definition​

  1. Navigate to the interface definition file:
  2. Copy the entire JSON content

Upload to FireFly​

Option 1: Using the Sandbox UI​

  1. Open the FireFly Sandbox for any node:

  2. Navigate to Contracts → Define a Contract Interface

  3. Paste the interface JSON content into the editor

  4. Update the version in the interface to match your deployed version (e.g., 1.0)

  5. Click Run to create the interface

Version Match

Ensure the version in the interface definition matches the version you deployed in Step 2. Mismatched versions will cause invocation errors.

Step 4: Register Contract API​

The final step is to register your chaincode as a callable API in FireFly.

Access the Registration Form​

  1. Open the FireFly Sandbox:

  2. Navigate to Contracts → Register Contract API

    Or use direct link: http://127.0.0.1:5108/home?action=contracts.api

Fill in the Registration Form​

Provide the following information:

FieldValueExample
Contract InterfaceSelect from dropdownThe interface you defined in Step 3
Namepackagename_X.Ypm3package_1.0
ChaincodeSame as Namepm3package_1.0
ChannelChannel namefirefly
Naming Convention

Use the format packagename_X.Y where:

  • packagename is your chaincode name (e.g., pm3package)
  • X.Y is your version number (e.g., 1.0)

This keeps your registrations organized and version-aware.

Complete Registration​

Click Register to complete the process.

Upon successful registration, your chaincode API will be available for invocation through FireFly's API endpoints and UI.

Verify Your Deployment​

Check Contract APIs​

  1. In the FireFly Sandbox, navigate to Contracts → Contract APIs
  2. You should see your newly registered API listed
  3. Click on it to view available methods

Test Invocation​

Try invoking a method to verify everything is working:

  1. Go to Contracts → Invoke Method
  2. Select your contract API
  3. Choose a method to test
  4. Provide required parameters
  5. Click Run
Sandbox Testing

The Sandbox provides an excellent environment for testing your chaincode methods before integrating them into your application.

Deployment Checklist​

Use this checklist to ensure you've completed all steps correctly:

  • Navigated to chaincodes/package directory
  • Created empty core.yaml file
  • Installed npm dependencies with npm install
  • Packaged chaincode with consistent version number
  • Deployed package to FireFly network
  • Retrieved interface definition from GitHub
  • Defined contract interface in FireFly
  • Verified interface version matches deployment
  • Registered contract API with correct parameters
  • Verified API appears in Contract APIs list
  • Tested at least one method invocation

Updating Chaincode​

When you need to update your chaincode:

Update Process​

  1. Increment the version number (e.g., from 1.0 to 1.1 or 2.0)
  2. Repeat the packaging process with the new version
  3. Deploy the new version to the network
  4. Update the interface with the new version
  5. Register the new API with the updated version number

Version Strategy​

# Bug fixes and minor changes
pm3package_1.0 → pm3package_1.1

# Breaking changes or major features
pm3package_1.0 → pm3package_2.0
Side-by-Side Versions

FireFly allows multiple versions of the same chaincode to coexist on the network, enabling gradual migration strategies.

Troubleshooting​

Package Creation Fails

Problem: Error during peer lifecycle chaincode package

Solutions:

# Ensure peer binary is accessible
which peer

# Verify you're in the correct directory
pwd  # Should show .../chaincodes/package

# Check core.yaml exists
ls -la core.yaml

# Verify npm dependencies are installed
ls -la node_modules
Deployment Fails

Problem: ff deploy command fails or hangs

Solutions:

# Stop the running firefly stack
ff stop dev

# Remove the stopped firefly stack
ff rm dev

Then recreate the stack and follow the same steps again according to the documentation. You can find the initalization step here.

Next Steps​

🎉 Congratulations! Your chaincode is now deployed and ready to use.

What's Next?​

  • Integrate with Applications: Use the FireFly API to call your chaincode from applications
  • Explore APIs: Review the FireFly API Documentation
  • Monitor Transactions: Use the FireFly UI to monitor blockchain transactions
  • Develop More Chaincodes: Apply this process to deploy additional smart contracts

Additional Resources​