fabnet

List and join blockchain networks using a remote fabnet registry

Usage no npm install needed!

<script type="module">
  import fabnet from 'https://cdn.skypack.dev/fabnet';
</script>

README

Fabnet client

Introduction

The Fabnet client is a command line tool to discover and join Hyperledger Fabric-based blockchain networks:

  • The Fabnet client can discover networks from a remote Fabnet server registry. By default, the command uses the online public registry available at https://fabnetworks.org, although alternative registry instances can be specified.

  • The Fabnet client can join networks that support automated onboarding. The Fabnet client can request permission to join, and subsequently retrieve any required network credentials and other artefacts.

The interactions between joiners, registry and networks are summarised here. In these instructions we're concerned with the tools in the  yellow  box.

fabnet flow

A user enters the fabnet command to interact with a registry that can list the details of known networks. They can then use a variant of the same command to request to join a network. Once joined, they can use the IBM Blockchain Platform web console to retrieve their certificate, using which they can transact with the network directly.

This package uses the Apache-2.0 license.

Getting started

Installing the Fabnet client

The Fabnet client command should work on any platform that supports npm; it has been tested on Windows, Ubuntu and MacOS.

  1. Ensure that you have Node 10 or greater installed. Fabnet has been tested with Node 10.

  2. Start a terminal prompt.

  3. Run the npm installer against the fabnet client package:

    npm install -g fabnet

  4. Verify that the package has been installed correctly by running the following command:

    fabnet --help

    fabnet options

    The --help flag will give you more information on what the command can do.

Using the Fabnet command to discover networks

  1. To browse the available networks listed in the default registry, run the command:

    fabnet list

    This will show you the networks that the connected registry knows about.

    List Fabnet Networks

  2. To display more information on the available networks, use the --full flag:

    fabnet list --full

  3. To connect an alternative registry, use the --server and/or --registry flags as directed by the registry's administrator:

    fabnet list --server my.server.example --registry myRegistry

  4. To learn about additional features of the fabnet list command, use the --help flag.

    fabnet list --help

Using the Fabnet command to join networks

You can attempt to join any network whose Available attribute (as shown by the list command) is marked as Yes.

Joining instructions can vary, and depend on both the structure of the network and the role that the joiner wishes to play. The Fabnet client supports an automated joining process, where enabled for the target network. This process allows valid email addresses to gain access to the network and uses a verification step to check that the address is active.

  1. Use the fabnet join command to specify the name of the network you want to join, and the email address you wish to register with.

    fabnet join --network DriveNet --user your@email.com

    You will receive an email containing a token. You must use this token to complete your registration.

    Email request - Inbox

  2. Re-run the fabnet join command, adding the --token flag to specify the token that you received.

    fabnet join --network DriveNet --user your@email.com --token yourToken

    When this command completes you will be shown the login details for your chosen network.

    The login details will vary from network to network. They typically include the Hyperledger Fabric enrollment ID and password, and an IBM Blockchain Platform web console URL, userid/password and a connection profile that client applications can use to connect.

    User completes join

    You will also receive an email that contains these details. Keep this email safe.

    User email confirmation body

  3. To complete your enrollment using the IBM Blockchain Platform web console, open a web browser and navigate to the IBM Blockchain Platform URL that you received, specifying the web console userid and password when prompted. You will need to change your password when you first log in.

  4. Use the IBM Blockchain Platform to retrieve your digital certificate so that you can interact with the network. Depending on the network configuration and your role within it, you might also need additional steps, such as registering your identity with an existing peer.

    For more details on the IBM Blockchain Platform, check out the product documentation.

  5. To learn about additional features of the fabnet join command, use the --help flag.

    fabnet join --help

Uninstalling the Fabnet client

  1. Once you have successfully joined a network, the Fabnet client is no longer required unless you wish to join more networks. If you wish to uninstall the command, enter the following:

    npm uninstall -g fabnet

Troubleshooting

I get an authorization error when installing

By default, some platforms (e.g. MacOS) do not allow the npm -g command to be run by users without administrative authority. If the installer fails with permission errors, you need to enable the root user and then run the command as root.

To enable the root user on MacOS, follow these instructions. Then install the Fabnet client by running 

sudo npm install -g fabnet

The Fabnet client should now be available for use.

I didn't receive my joining email

When you attempt to join a network that supports automated joining, you will receive an email that contains a token that you must use to finalize your registration. If you don't receive your joining email, please check your spam folder. The email will be from blockchain@uk.ibm.com.

Not all networks listed in the registry support automated joining. If you are unsure of the process for joining a particular network, contact an administrator if one is listed.

back to top