Manage Ordering Service

This topic contains information about how founders and participants manage the ordering service.

Additionally, several channel-specific tasks for the orderer nodes can be performed on the Channels page of the console. See:

What is the Ordering Service?

In Oracle Blockchain Platform v20.3.1 and later, we support Raft as our consensus type.

For more information on the Raft protocol, see: The Ordering Service - Raft.

With the older Kafka consensus type, the whole network can have at most two orderer nodes, and they have to join all channels. In some cases, they may be overloaded, and cannot be scaled out. With the Raft consensus type, the network can have an arbitrary number of orderer nodes, and each channel can define its own orderer node set. Different channels can use different orderer nodes, and orderer nodes will no longer be the bottleneck.

However, the Raft consensus type can be complicated to configure properly. There are rules about what can or can't be done, and if these rules are not followed the channel and even the network may not work. The following guidelines should reduce the problems you encounter:

Keep the Majority of the Ordering Service Nodes (OSN) Alive

The Raft consensus algorithm requires that the majority of ordering service nodes (OSNs) are working; otherwise no consensus can be made. Majority means greater than 50%. For example, for five OSNs, there must be at least three OSNs working; for six OSNs, there must be at least four OSNs working.
  • If there are 50% or less OSNs working in the network, network management will no longer be functional. No new channels can be created, no new orderer nodes can be added into network, no orderer can be removed from network, and so on.
  • If there are 50% or less OSNs working in the application channel, no transaction can be submitted to this application channel. Queries may still function correctly, however administrative operations such as adding a new organization, changing the access control list, or instantiating chaincodes will fail.

Be cautious when adding a new OSN to the network or an application channel. Ensure the owner is trustworthy and the OSN is robust.

Do Not Add or Remove Orderers Frequently

Every time a new OSN is added into a network or channel, or an existing OSN is removed from a channel, the current Raft OSN cluster will briefly become unstable. During this period, no transactions can be handled, and an error message similar to the following may indicate such a status:
UNKNOWN: Stream removed
SERVICE UNAVAILABLE
BAD REQUEST

This may last a few minutes. If you have removed the previous Raft leader OSN from the channel, this may last as long as 20 minutes.

Ensure that you aren't adding or removing orderers frequently. If multiple orderers must be added or removed, do one at a time ensuring that the network has returned to operational status before making the next change.

Ensure the New Orderer is Started As Soon As Possible

When adding a new orderer into network, usually two organizations will be involved: the founder and the owner of the new orderer. Both parties must follow the instructions in Join the Participant or Scaled-Out OSNs to the Founder's Ordering Service all the way to completion or the founder won't be able to manage the network.

Join the Participant or Scaled-Out OSNs to the Founder's Ordering Service

When you provision a participant instance, it is created with either 1 or 3 orderers depending on the edition you have chosen. There orderers are inactive until they are joined to a network. When you scale out a founder, the new orderers are also inactive until they are joined to a network.

Export the OSN Settings From the Participant or Scaled-Out Orderers

To join the participant or scaled-out orderers to a network, you need to export their settings and import them into the founder.

  1. In the participant console (or the founder console for scaled-out orderers), on the Node tab find the orderer node (or the first orderer node if multiple nodes exist). Select the Action menu for this node and select Export OSN Settings.

    This will generate a JSON file with the settings and save the file. The file contains the organization's certificate and the selected orderer service node (OSN) settings signed by the private key of the administrator of the participant organization. This file needs to be sent to the administrator of the founder instance.

    Applications being run on channels using this OSN also require this exported TLS certificate. See Before You Develop an Application.

    Repeat this step for each OSN being added to the founder network.

  2. In the founder console, open the Network tab. Click Add OSN. A window opens prompting you for the location of the JSON file provided by the participant. Select to upload the file and click Add.

    The participant organization or newly scaled-out orderer will be added to the orderer organization section of the system channel list.

    Repeat this for each OSN being added to the founder network.

Export the Founder's Configuration Settings

Once the participant or scaled-out orderers have been added to the founder, you need to export the founder's settings and import them to the participant or scaled-out orderer.

  1. In the founder console, open the Network tab. Click Export Network Config Block.

    The network configuration block contains the latest system channel configuration block. This can be saved and sent to the participant administrator.

  2. In the participant console (or the founder console for scaled-out orderers), on the Node tab find the orderer node (or the first orderer node if multiple nodes exist). Select the Action menu for this node and select Import Network Config Block.

    You'll be prompted for the file sent by the founder instance administrator.

    Repeat for each orderer node.

  3. In the participant console, refresh the Node tab. The orderer node status should be listed as "down". From the Action menu select Start.

    Each orderer node started will be added to the Raft cluster in the founder.

Each time a new OSN is added by scaling out the orderer (as described in Scale Your Instance) these steps need to be repeated to add the new OSN to the Raft cluster.

Note:

You can't add multiple OSNs into a network in a single batch. Ensure only 1 OSN is added at a time.

Edit Ordering Service Settings for the Network

You can update the ordering service settings for the founder instance.

Note the following important information about editing the ordering service settings:
  • The updated settings are used when you create new channels and are not applied to existing channels.
  • Separately you can update the ordering service settings for an individual existing channels as described in Edit Ordering Service Settings for a Channel.
  • If you change the ordering service settings and there are applications running against the network, then those applications must be manually updated to use the revised ordering service settings.
  • It isn’t common, but in some situations, you might expose a different ordering service to some of the network participants. In this case, you’ll export the updated network config block and the required participants will import the revised settings. See Join the Participant or Scaled-Out OSNs to the Founder's Ordering Service.
You must be an administrator to perform this task.
  1. Go to the founder’s console and select the Network tab.
  2. Click the Ordering Service Settings button.
    The Ordering Service Settings dialog is displayed.
  3. Update the settings as needed.
    Field Description
    Batch Timout (ms) Specify the amount of time in milliseconds that the system should wait before creating a batch. Enter a number between 1 and 3600000.
    Max Message Count Specify the maximum number of message to include in a batch. Enter a number between 1 and 4294967295.
    Absolute Message Bytes Specify the maximum number of bytes allowed for the serialized messages in a batch.

    This number must be larger than the value you enter in the Preferred Message Bytes field.

    Preferred Message Bytes Specify the preferred number of bytes allowed for the serialized messages in a batch. A message larger than this size results in a larger batch, but the batch size will be equal to or less than the number of bytes you specified in the Absolute Message Bytes field.

    Oracle recommends that you set this value to 1 MB or less.

    The value that you enter in this field must be smaller than the value you enter in the Absolute Message Bytes field.

    Snapshot Interval Size Defines number of MB per which a snapshot is taken.
  4. Click Update.
    The updated settings are saved.

View Ordering Service Settings

You can view the founder's ordering service settings that were imported into a participant’s Oracle Blockchain Platform instance.

If the founder changes the ordering service settings the new settings must be ported to the participant as described in Join the Participant or Scaled-Out OSNs to the Founder's Ordering Service. If there are applications running against the network, then those applications must be manually updated to use the revised ordering service settings.
  1. Go to the participant’s console and select the Network tab.
  2. Click Ordering Service Settings and click View.
    The Ordering Settings dialog is displayed.