Overview

What are plugins?

Plugins are a way to extend the functionality of ChainLaunch. They can be written in any language since they are deployed to Docker containers using docker-compose. Plugins allow you to add custom functionality, APIs, monitoring tools, or any other services that integrate with your blockchain networks.

Plugin Structure

A plugin is defined using a YAML configuration file with the following structure:

apiVersion: dev.chainlaunch/v1
kind: Plugin
metadata:
    name: plugin-name
    version: '1.0'
    description: "Plugin description"
    author: "Author name"
    tags:
        - tag1
        - tag2
    repository: "https://github.com/org/repo"
    license: "Apache-2.0"

spec:
    dockerCompose:
        contents: |
            # Docker Compose configuration
    parameters:
        # Parameter schema
    documentation:
        readme: |
            # Plugin documentation
        examples:
            # Usage examples
        troubleshooting:
            # Troubleshooting guides

Key Components

Metadata

• name: Unique identifier for the plugin
• version: Plugin version
• description: Brief description of functionality
• author: Plugin author/creator
• tags: Categories for organization
• repository: Source code location
• license: License information

Docker Compose

Defines the containerized services that make up the plugin. Uses templating to inject dynamic values from parameters.

Parameters

JSON schema defining the configuration parameters the plugin accepts, including:

• Input validation rules
• Parameter types and descriptions
• Required vs optional parameters
• Integration with ChainLaunch data sources (using x-source)

Documentation

Comprehensive documentation including:

• README: Detailed usage instructions
• Examples: Common use cases and configurations
• Troubleshooting: Common issues and solutions

How to create a plugin?

You only need a YAML file to create a plugin. The plugin system handles the deployment and management automatically based on your configuration.

Example Plugin

Here's an example of a Hyperledger Fabric API plugin:

apiVersion: dev.chainlaunch/v1
kind: Plugin
metadata:
    name: hlf-plugin-api
    version: '1.0'
    description: "Hyperledger Fabric API plugin that provides a REST API interface to interact with Fabric networks"
    author: "ChainLaunch Team"
    tags:
        - fabric
        - api
        - rest
        - chaincode
    repository: "https://github.com/kfsoftware/plugin-hlf-api"
    license: "Apache-2.0"

spec:
    dockerCompose:
        contents: |
            version: '2.2'
            services:
              app:
                image: ghcr.io/kfsoftware/plugin-hlf-api:main-9e27cb5
                command: 
                  - serve
                  - --mspid={{ .parameters.key.MspID }}
                  - --cert={{ .parameters.key.CertPath }}
                  - --key={{ .parameters.key.KeyPath }}
                  - --peers={{- range $i, $peer := .parameters.peers }}{{if $i}},{{end}}{{$peer.ExternalEndpoint}}{{- end }}
                  - --channel={{ .parameters.channelName }}
                  - --port={{ .parameters.port }}
                  - --tlscerts={{- range $i, $peer := .parameters.peers }}{{if $i}},{{end}}{{$peer.TLSCACertPath}}{{- end }}
                ports:
                  - "{{ .parameters.port }}:{{ .parameters.port }}"
                volumes:
                  {{- range .volumeMounts }}
                  - {{ .Source }}:{{ .Target }}:{{ if .ReadOnly }}ro{{ else }}rw{{ end }}
                  {{- end }}

    parameters:
        $schema: http://json-schema.org/draft-07/schema#
        type: object
        properties:
            key:
                type: object
                title: Key
                description: The key to use for the API
                x-source: fabric-key
            channelName:
                type: string
                title: Channel Name
                description: The channel name to use for the API
            peers:
                type: array
                title: Peers
                description: The peers to use for the API
                x-source: fabric-peer
            port:
                type: number
                title: Port
                description: The port to use for the API
        required: []

    documentation:
        readme: |
            # Hyperledger Fabric API Plugin

            This plugin provides a REST API interface to interact with Hyperledger Fabric networks, allowing you to query and invoke chaincode operations through HTTP endpoints.

            ## Features
            - REST API interface for Fabric operations
            - Support for multiple peers
            - TLS certificate management
            - Chaincode query and invoke operations
            - Channel management

            ## Prerequisites
            - A running Hyperledger Fabric network
            - Valid MSP certificates and keys
            - Access to peer nodes
            - Chaincode installed and instantiated

            ## Configuration
            The plugin requires the following parameters:
            - `key`: Fabric key with MSP ID, certificate, and private key
            - `channelName`: Name of the Fabric channel
            - `chaincodeName`: Name of the chaincode to interact with
            - `peers`: List of peer nodes to connect to
            - `port`: Port for the API server

            ## API Endpoints
            The plugin exposes the following endpoints:
            - `GET /api/v1/query`: Query chaincode
            - `POST /api/v1/invoke`: Invoke chaincode
            - `GET /api/v1/channel`: Get channel information
            - `GET /api/v1/health`: Health check endpoint

        examples:
            - name: "Basic Chaincode Query"
              description: "Configure the API to query a basic chaincode"
              parameters:
                key:
                  MspID: "Org1MSP"
                  CertPath: "/etc/hyperledger/crypto/peer/cert.pem"
                  KeyPath: "/etc/hyperledger/crypto/peer/key.pem"
                channelName: "mychannel"
                chaincodeName: "mycc"
                peers:
                  - ExternalEndpoint: "peer0.org1.example.com:7051"
                    TLSCACertPath: "/etc/hyperledger/crypto/peer/tls/cert.pem"
                port: 8080

            - name: "Multi-Peer Configuration"
              description: "Configure the API to work with multiple peers for redundancy"
              parameters:
                key:
                  MspID: "Org1MSP"
                  CertPath: "/etc/hyperledger/crypto/peer/cert.pem"
                  KeyPath: "/etc/hyperledger/crypto/peer/key.pem"
                channelName: "mychannel"
                chaincodeName: "mycc"
                peers:
                  - ExternalEndpoint: "peer0.org1.example.com:7051"
                    TLSCACertPath: "/etc/hyperledger/crypto/peer0/tls/cert.pem"
                  - ExternalEndpoint: "peer1.org1.example.com:7051"
                    TLSCACertPath: "/etc/hyperledger/crypto/peer1/tls/cert.pem"
                port: 8080

        troubleshooting:
            - problem: "API cannot connect to peers"
              solution: |
                ### Quick Fix
                1. Verify peer connectivity:
                   ```bash
                   docker-compose exec app ping peer0.org1.example.com

2. Check TLS certificates:

   ls -la /etc/hyperledger/crypto/peer/tls/
3. Validate peer endpoints:

   cat /etc/hyperledger/config/connection-profile.yaml

Common Issues

• Invalid TLS certificates
• Network connectivity problems
• Incorrect peer endpoints
• Firewall blocking access

Resolution Steps

1. TLS Certificate Issues

   • Verify certificate paths
   • Check certificate validity
   • Ensure proper permissions

2. Network Issues

   • Check DNS resolution
   • Verify network policies
   • Test peer connectivity

3. Configuration Issues

   • Validate connection profile
   • Check MSP configuration
   • Verify channel configuration description: "This issue occurs when the API cannot establish connections to the Fabric peer nodes."

• problem: "Chaincode operations failing" solution: |

  Quick Fix

  1. Verify chaincode status:

     peer chaincode list --instantiated -C mychannel
  2. Check chaincode logs:

     docker-compose logs app | grep chaincode
  3. Validate chaincode policy:

     peer chaincode query -C mychannel -n mycc -c '{"Args":["query","a"]}'

  Common Issues

  • Chaincode not instantiated
  • Incorrect chaincode name
  • Policy violations
  • Endorsement failures

  Resolution Steps

  1. Chaincode Installation

     • Verify chaincode is installed
     • Check instantiation status
     • Validate chaincode version

  2. Policy Issues

     • Review endorsement policy
     • Check organization permissions
     • Verify channel configuration

  3. Query/Invoke Issues

     • Validate input parameters
     • Check chaincode logic
     • Review error messages description: "This issue occurs when chaincode operations fail due to various reasons."

• problem: "API server not starting" solution: |

  Quick Fix

  1. Check container logs:

     docker-compose logs app
  2. Verify port availability:

     netstat -tulpn | grep 8080
  3. Check configuration:

     docker-compose config

  Common Issues

  • Port conflicts
  • Invalid configuration
  • Missing dependencies
  • Permission issues

  Resolution Steps

  1. Port Issues

     • Change port number
     • Stop conflicting services
     • Check firewall rules

  2. Configuration Issues

     • Validate parameter values
     • Check environment variables
     • Review volume mounts

  3. Dependency Issues

     • Verify image availability
     • Check network connectivity
     • Validate volume permissions description: "This issue occurs when the API server fails to start properly."

## Next Steps

To get started with plugins:
1. Review the [List of Plugins](./list) to see available plugins
2. Choose a plugin that fits your needs
3. Configure the plugin parameters
4. Deploy and test the plugin functionality