Bring up firefly-fabconnect

This documentation shows several ways to deploy firefly-fabconnect:

• Using fabconnect and the Fabric test-network in the samples repository.

  This mode runs an instance of fabconnect using a docker container managed by docker-compose.

• Using fabconnect and the Fabric test-network-nano-bash in the samples repository.

  This mode runs an instance of fabconnect compiled from source code.

• Using FireFly CLI

  FireFly CLI mode runs some supernodes on your machine. The stack contains an instance of firefly-core, firefly-dataexchange-https, ipfs, and firefly-sandbox.

  👀 Si entiendes el español no dudes en visitar el README-ES.

Table of Contents

• Using fabconnect and the Fabric test-network
  • Download fabric-samples, docker images, and fabric binaries
  • Bring up the test network
  • Download configuration
  • Bring up fabconnect
• Using fabconnect and the Fabric test-network-nano-bash
  • Bring up "test-network-nano-bash"
  • Download and build fabconnect
  • Download configuration
  • Modify the cpp file for test-network-nano-bash
  • Launch the connector
• Using firefly-cli
  • Download and install the CLI
  • Create a stack of Hyperledger Fabric
  • Configuration files
• Interacting with the asset-transfer-basic chaincode
  • In fabconnect mode with Fabric's test-network or test-network-nano-bash
  • In firefly-cli mode
• Documentation
• Troubleshooting

Using fabconnect and the Fabric test-network

This mode runs an instance of fabconnect using a docker container managed by docker-compose.

NOTE: This mode has only been tested on Ubuntu 20.04.

Download fabric-samples, docker images, and fabric binaries

cd $HOME

To get the install script:

curl -sSLO https://raw.githubusercontent.com/hyperledger/fabric/main/scripts/install-fabric.sh && chmod +x install-fabric.sh

Run the script:

./install-fabric.sh -f 2.4.4 d b s

NOTE: These arguments download the Fabric Images 2.4.4 version, clone the fabric-samples repository, and download the Fabric binaries.

Visit this link for better instructions...

Bring up "test-network"

cd fabric-samples/test-network

Run the following command to start the network, create a channel with mychannel default name, and generate the cryptographic artifacts with the Fabric CA:

./network.sh up createChannel -ca -c mychannel

Download configuration

Download this repository

git clone https://github.com/kmilodenisglez/fabconnect-testnet.git

NOTE: This repository has a docker-compose file that starts a firefly-fabconnect container. It is configured to mount the cryptographic artifacts volume from $HOME/fabric-samples/test-network/organizations/.

cd fabconnect-testnet

Bring up fabconect

docker-compose up -d

Visit the url: http://ip_address_here:3000/api

Using fabconnect and the Fabric test-network-nano-bash

In this mode, an instance of fabconnect that we built from the source code is used.

NOTE: This mode has been tested on Ubuntu and on Windows 10 with WSL. The network was bring up with the minimum configuration, with two orderer nodes (./orderer1.sh and ./orderer2.sh) and a single Org1 peer node (./peer1.sh).

Bring up "test-network-nano-bash"

👉🏾 Follow the instructions to bring up network and install the chaincode.

Download and build fabconnect

cd $HOME

Download the fabconnect repository

git clone https://github.com/hyperledger/firefly-fabconnect.git

Compile fabconnect

go mod vendor
go build -o fabconnect

Move fabconnect binary to /usr/bin/local

 chmod +x fabconnect && sudo cp fabconnect /usr/local/bin/

cd $HOME

Download configuration

Download this repository

git clone https://github.com/kmilodenisglez/fabconnect-testnet.git

Modify the cpp and fabconnect files for test-network-nano-bash

Modify in the fabconnect-testnet/runtime/blockchain/cpp_nanobash.yaml file the path to the artifacts. Wherever you find '/home/my_user/fabric-samples' you replace it with the path to your fabric-samples.

Modify in the fabconnect-testnet/runtime/blockchain/fabconnect_nanobash.yaml file the paths. Wherever you find '/home/my_user/fabconnect-testnet' you replace it with the path to your fabconnect-testnet.

Launch the connector

Before starting the fabconnect we must configure the identity (signer) that will be used to establish a connection with the blockchain network. The test-network-nano-bash does not bring up Fabric-CA nodes, so you have to use the admin or user1 identity generated by the generate_artifacts.sh script.

We open in a file explorer the path where the credentials are stored. The path is defined in the CCP file "cpp_nanobash.yaml", in the client.credentialStore section.

For this example the fabric-samples/test-network-nano-bash is in the home directory.

cd ~/fabric-samples/test-network-nano-bash/crypto-config/peerOrganizations/org1.example.com/users/

Copy the Admin@org1.example.com-cert.pem to the root directory of /users with the following format user + @ + MSPID + "-cert.pem" :

cp Admin@org1.example.com/msp/signcerts/Admin@org1.example.com-cert.pem ./admin@Org1MSP-cert.pem

Copy the User1@org1.example.com-cert.pem to the root directory of /users with the following format user + @ + MSPID + "-cert.pem" :

cp User1@org1.example.com/msp/signcerts/User1@org1.example.com-cert.pem ./user1@Org1MSP-cert.pem

NOTE: It is the format used by fabric-sdk-go to store a user.

Copy and rename each user's priv_sk private key to the /users/keystore/ directory:

Admin private key:

mkdir -p ./keystore && cp Admin@org1.example.com/msp/keystore/priv_sk ./keystore/admin_sk

Private key of user1:

mkdir -p ./keystore && cp User1@org1.example.com/msp/keystore/priv_sk ./keystore/user1_sk

The structure should look like this:

my_user@208996:~/fabric-samples/test-network-nano-bash/crypto-config/peerOrganizations/org1.example.com/users$ ls -l
drwxr-xr-x 4 my_user my_user 4096 Jul 19 09:59 Admin@org1.example.com
-rw-rw-r-- 1 my_user my_user 810  Jul 19 10:22 admin@Org1MSP-cert.pem
drwxrwxr-x 2 my_user my_user 4096 Jul 19 10:28 keystore
drwxr-xr-x 4 my_user my_user 4096 Jul 19 09:59 User1@org1.example.com
-rw-rw-r-- 1 my_user my_user 810  Jul 19 10:23 user1@Org1MSP-cert.pem

Use the following command to launch the connector:

fabconnect -f "/home/my_user/fabconnect-testnet/runtime/blockchain/fabconnect_nanobash.yaml"

Using firefly-cli

Download and installation the CLI

Follow the steps from the official README for download and install from the cli.

Create a stack of Hyperledger Fabric

The ff init command creates a new stack and will prompt you for a few details, such as the members number (organizations), the organization(s) name and peer nodes name.

ff init -b fabric --prompt-names stack-fabric

Once the execution of the command has finished, you should see an output similar to this:

initializing new FireFly stack...
number of members: 1
name for org 0: org1
name for node 0: peer1
Stack 'stack-fabric' created!
To start your new stack run:

  ff start stack-fabric

NOTE: In this example the stack stack-fabric was created with a single member named "org1" and a node named "peer1".

Configuration files

NOTE: The configuration files for each stack are located in ~/.firefly/stacks/

Interacting with the asset-transfer-basic chaincode

In fabconnect mode with Fabric's test-network or test-network-nano-bash

• If you operate with the test-network you can install the asset-transfer-basic chaincode with the steps: Install the asset-transfer-basic on test-network

• If you operate with test-network-nano-bash you can install the asset-transfer-basic chaincode with the steps: Install the asset-transfer-basic on test-network-nano-bash

NOTE: To interact with the fabconnect endpoints you can access the link http://ip_address:3000/api in your browser.

InitLedger

Invoke the POST /transactions endpoint, with the following data:

{
  "headers": {
    "type": "SendTransaction",
    "signer": "admin",
    "channel": "mychannel",
    "chaincode": "basic"
  },
  "func": "InitLedger",
  "args": [],
  "init": false
}

As a result, the client should respond with a JSON similar to this:

{
  "headers": {
    "id": "cee5a0b8-e207-49c9-76a2-ca0d106fa139",
    "type": "TransactionSuccess",
    "timeReceived": "2022-07-18T06:00:37.323214822Z",
    "timeElapsed": 2.217562622,
    "requestOffset": "",
    "requestId": ""
  },
  "blockNumber": 6,
  "signerMSP": "Org1MSP",
  "signer": "admin",
  "transactionID": "44574737473df89f0183827f10ede4b5e99563ba44df6b7d48a49763d9179228",
  "status": "VALID"
}

QueryAllAssets

Invokes the POST /query endpoint, with the following data:

{
  "headers": {
    "signer": "admin",
    "channel": "mychannel",
    "chaincode": "basic"
  },
  "func": "GetAllAssets",
  "args": [],
  "strongread": true
}

As a result, the client should respond with a JSON similar to this:

{
  "headers": {
    "channel": "mychannel",
    "timeReceived": "",
    "timeElapsed": 0,
    "requestOffset": "",
    "requestId": ""
  },
  "result": [
    {
      "AppraisedValue": 300,
      "Color": "blue",
      "ID": "asset1",
      "Owner": "Tomoko",
      "Size": 5
    },
    {
      "AppraisedValue": 400,
      "Color": "red",
      "ID": "asset2",
      "Owner": "Brad",
      "Size": 5
    },
    ...
  ]
}

In firefly-cli mode

If you use firefly-cli you can install and interact with the asset-transfer-basic chaincode by following the steps: Working asset-transfer-basic with firefly-cli

Documentation

• FireFly Fabconnect - Github
• FireFly Cli - Github
• Firefly - Doc

Troubleshooting

If fabconnect returned any TRANSIENT_FAILURE errors, one possible reason is that you need to add the domain names "peer0.org1.example.com", "orderer.example.com", and "org1.example.com" to the hosts ".

Run the following:

echo '127.0.0.1 peer0.org1.example.com orderer.example.com org1.example.com' | sudo tee -a /etc/hosts