fabric-channeled-add-ons-gen is an open-source generator for Hyperledger Fabric add-on apps in dedicated channels. Inspired by the increasing utilization of browser extensions, fabric-channeled-add-ons-gen provides a solution for deploying user-managed applications on different Hyperledger Fabric channels in the form of add-ons.
Contributors on fabric-channeled-add-ons-gen can bring their own business intelligence or browser support, and extend the generator beyond the initial release that consists of the asset-transfer-basic workflow.
fabric-channeled-add-ons-gen provides flexible configuration and deployment of add-on applications in separate Fabric channels by automating:
- User management
- Deployment as browser add-on
- Data privacy through channels
fabric-channeled-add-ons-gen is an open-source generator, suitable for Hyperledger Fabric networks, where the applications are deployed as add-ons for a separate channel with easy user management in mind.
The application is written in Typescript (4.8) and express (4.18). It is based on the newly introduced Gateway service (Fabric 2.4), but can be easily adjusted to work with older versions as well.
The extension is written in React (18.2) Typescript (4.8). For routing between the views, React Router (6.4) was used. We used fetch API for communicating with the application.
Here, the classic asset-transfer-basic
chaincode is deployed as an example case, in chaincode
directory (GO v1.18).
In order to deploy another application, simply replace asset-transfer-basic
.
The following functions are implemented by default:
- CreateAsset
- ReadAsset
- UpdateAsset
- DeleteAsset
- TransferAsset
- AssetExists
The user management chaincode creates ten (10) user accounts by default for the application chaincode selected above. The implemented user-related functions are:
- UserExists
- CreateUser
- ReadUser
- GetAllUsers
Note that the asset transfer implemented by the smart contract is a simplified scenario, without ownership validation, meant only to demonstrate how to invoke transactions.
The Fabric test network is used to deploy and run this sample. Follow these steps in order:
0. Install Hyperledger Fabric and get the fabric-samples
.
Instructions can be found on the Fabric v2.4 documentation.
curl -sSL https://bit.ly/2ysbOFE | bash -s #-- 2.4.6 1.5.3
cd fabric-samples/
-
Clone fabric-channeled-add-ons-gen inside the
fabric-samples
folder.cd fabric-samples/ git clone https://github.com/hyperledger-labs/fabric-channeled-add-ons-gen.git
-
Create the test network and a channel (from the
test-network
folder).cd test-network/ ./network.sh up createChannel -c mychannel -ca
-
Chaincode deployment of i) the user-management and ii) the selected application (here
asset-transfer-basic
)../network.sh deployCC -ccn asset_basic -ccp ../fabric-channeled-add-ons-gen/chaincode/asset-chaincode -ccl go ./network.sh deployCC -ccn user_basic -ccp ../fabric-channeled-add-ons-gen/chaincode/user-chaincode -ccl go
-
Running the application. For running the app in docker, look at step 5. Rename the
.env.example
file to.env
and set a strong password forCOOKIES_SECRET
. This is the only configuration needed to be set up for now.cd ../fabric-channeled-add-ons-gen/application mv .env.example .env # Set strong password for `COOKIES_SECRET` npm install npm start
-
(Optional) Running the application in docker. To run the application in docker, the environmental variables of
LOCAL_CRYPTO_PATH
,PEER_ENDPOINT
andCOOKIES_SECRET
need to at least be set. Some sensible default values are the ones below (also in.env.example
):LOCAL_CRYPTO_PATH=../test-network/organizations/peerOrganizations/org1.example.com ... PEER_ENDPOINT=peer0.org1.example.com:7051
Then go to the root folder and run docker compose with a specified env file pointing on the
application/.env
file mentioned above.cd .. docker compose --env-file application/.env up -d
-
Building the add-on app (
extension/
directory). First rename the.env.example
to.env
. Necessary changes should be made in the.env
file at a latter step where more applications are enabled through the generator.cd ../extension mv .env.example .env npm install npm run build
-
Install the add-on as a browser extension.
On Google Chrome or Edge go to Settings -> Extensions, enable developer mode and then click load unpacked and select the
/build
folder of the extension. -
Use the given credentials.
The private keys for the users created on startup are printed on the application logs. Copy the name and the private key and paste them on the extension. For server address the location of the application should be used, for example
http://localhost:8000
.
fabric-channeled-add-ons-gen enables the easy generation and deployment of new apps (here, asset-transfer-basic
) in other channels (here, channel2
).
-
Create a new channel.
cd ../../test-network ./network.sh createChannel -c channel2 -ca
-
Select the new channel to deploy to.
./network.sh deployCC -c channel2 -ccn othercc -ccp ../fabric-channeled-add-ons-gen/chaincode/ -ccl go
-
Before starting the application edit the
application/.env
file and set the environmental variables:COOKIES_SECRET
,CHANNEL_NAME
,CHAINCODE_NAME
, and theAPP_PORT
if running on same environment):APP_PORT=8001 COOKIES_SECRET=(...) CHANNEL_NAME=channel2 CHAINCODE_NAME=othercc
Now start the application in a new terminal (or add another app to the
docker-compose.yml
file).cd ../fabric-channeled-add-ons-gen/application/ # Set strong password for `COOKIES_SECRET` npm start
-
Use the add-on to connect to the new channel, using the appropriate application port and address.
Close all applications:
To stop the application, if running on terminal, you can stop it with Cntrl+C
, by sending it SIGTERM. If using the docker container,
docker-compose down
should do.
Bring down the test network (from the test-network
folder). The command will remove all the blockchain nodes, and delete any ledger data created.
cd ../../test-network
./network.sh down
In order to use a different sample, or tailor the add-on to your business needs, the asset chaincode needs to be adapted. The user chaincode is separated and can be used so.
For the asset chaincode, the core things that need to be changed are:
In the API/backend level (application
folder):
- The ledger folder contains all the code related with the interaction with the chaincode, so all chaincode functionality should be encoded as functions there.
- The API code is found in
routes
. Theassets.routes.ts
contains all the API endpoints related with the interaction with the assets. The endpoints there could be adjusted to your needs.
On the add-on side:
- All the interaction with the API is mapped inside the
services
folder, and especially theAssetTransferService.ts
. Depending on your use case, this functionality could be adjusted. - Everything else has to be edited based on the UI you would be interested in presenting to your audience.
- Initial version supported an asset-transfer-basic workflow on Google Chrome and Microsoft Edge.
- Inspired by Hyperledger Labs Hyperledger Fabric Chrome Extension
- Enable private data collections integrations for dApps.