Configure Oracle Blockchain Platform for the Wholesale CBDC Sample Application

After you've created all the required instances of Oracle Blockchain Platform and it's prerequisite products, you'll need to configure your users and roles, add any participant organizations to the founder organization, and enable the rich history database.

Configure IDCS Groups to Oracle Blockchain Platform Instances

For additional information on the built-in Oracle Blockchain Platform roles and how to assign users to them, see Set Up Users and Application Roles

For additional information on the wholesale CBDC sample application roles, see Wholesale CBDC Application Workflow.

In Oracle Blockchain Platform, the following application role assignments should be implemented:

Central Bank (CB) Groups: Assign all Central Bank groups to the REST_CLIENT application role of CentralBank Oracle Blockchain Platform instance.
Financial Institution (FI) Groups: Assign all Financial Institution groups to the REST_CLIENT application role as well of their respective organization.
Administrative Roles: Assign the relevant administrative groups, such as CB_CBDC_ADMIN and FI_CBDC_ADMINS, to the ADMIN application role of their respective organization.

This configuration ensures that both Central Bank and Financial Institution groups have the necessary access through the REST_CLIENT role, while administrative privileges are appropriately managed through the ADMIN role.

Follow these steps to assign the groups to application roles.

Sign in to your Oracle Cloud Infrastructure account.
In the Console, click the Navigation menu in the top-left corner.
Under Identity, select Domains.
On the Domains page, click Oracle Identity Cloud Service.
In the Oracle Identity Cloud Service navigation menu, select Oracle Cloud Services. Locate the Oracle Blockchain Platform instance for which you want to assign group roles. Open that instance's Details page.
Go to the Application Roles tab to view the Oracle Identity Cloud Service application roles listed in the Resources navigator.
Select the role you want to assign, and expand the role. Click the More menu for the role and select Assign Groups.
In the Assign Groups dialog, select the groups you want to assign to the role, and click Assign.

Fetch ClientId and ClientSecret

The Oracle Blockchain Platform ClientID and ClientSecret will be utilized by Visual Builder. You'll need to update these parameters in Visual Builder later as described in Configure Visual Builder Backends.

To retrieve the client ID and client secret for an Oracle Blockchain Platform instance:

Sign in to your Oracle Cloud Infrastructure account. Ensure that you have sufficient administrative privileges to manage OAuth settings.
In the Console, click the Navigation menu in the top-left corner.
Under Identity, select Domains.
On the Domains page, click Oracle Identity Cloud Service.
In the Oracle Identity Cloud Service navigation menu, select Oracle Cloud Services. Locate the Oracle Blockchain Platform instance for which you want to fetch the client ID and client secret. Open that instance's Details page.
When you open the instance details page, the default tab displayed will be the OAuth Configuration tab. This tab contains essential information regarding OAuth settings for your Oracle Blockchain Platform instance.
You will find fields labeled Client ID and Client Secret in the General Information section. These credentials are used to authenticate API requests to the Oracle Blockchain Platform.

Multiple Organization Configuration

If you're creating a complex Oracle Blockchain Platform network with multiple organizations, add participants to the founder. An overview of this process is provided in the Oracle Blockchain Platform Admin Guide: Add OBCS Participant Organizations to the Network.

Configure the Rich History Database for Oracle Blockchain Platform

For additional information about configuring and using the rich history database, see Create the Rich History Database .

Before completing these steps, you must have created an Autonomous Database instance as described in Provision Autonomous Database in order to enable the rich history database for Oracle Blochain Platform.

Open the Oracle Blockchain Platform console for the network instance.
Click on the More Actions menu in the top-right corner and select Configure Rich History.
Specify an Oracle database connection by providing the connection string and credentials to access and write to the Oracle database. Note that the credentials you provide are the database's credentials and Oracle Blockchain Platform doesn't manage them.
Click Save to configure the rich history database.

Create Enrollments

You must manually create the enrollments for the users in CB_CBDC_ADMINS and FI_CBDC_ADMINS groups.

Enrollments in the Oracle Blockchain Platform's REST proxy provide a mechanism for users to interact with the blockchain without requiring an enrollment certificate, simplifying API calls by mapping application identities to blockchain members. To initiate any call to the chaincode, enrollments must be established within the Oracle Blockchain Platform.

The wholesale CBDC application manages the creation of enrollments for users during account setup; however, when a CBDC Admin user logs in for the first time, no enrollment exists. Consequently, if this user attempts to create an account, the RestProxy call will fail. Therefore, it is essential to create an enrollment for the CBDC ADMIN group.

When setting up accounts, enrollments are created for the respective organizations. For instance, when accounts for the Central Bank (CB) are established, corresponding enrollments will be generated. However, if any Financial Institution (FI) accounts are created through the CBDC Admin page, enrollments will not be automatically created for those FIs. In this wholesale CBDC workflow, it is necessary to set up FI admin accounts within the CB Admin page. Therefore, users must manually create enrollments for the FI Admin group as these enrollments will not be generated automatically due to the distinct organizational structure between the Central Bank and Financial Institutions.

Refer to Add Enrollments to a REST Proxy for comprehensive information on how to create the enrollments.

Fetch RestproxyId

The RestproxyId will be utilized by Visual Builder. You'll need to update this in Visual Builder later as described in Configure Visual Builder Backends.

To retrieve the RestProxyId for an Oracle Blockchain Platform instance, users must invoke the Oracle Blockchain Platform console APIs using an administrative user account. Authentication can be performed via either basic authentication or OAuth 2.0.

Authentication Method

For OAuth 2.0, refer to the documentation at OAuth 2.0 Access Token Based Authentication to implement the necessary authentication flow.

API Endpoint for Fetching RestProxyId

Use the Oracle Blockchain Platform console API to obtain the RestProxyId by sending a request to the following endpoint:

GET <obp_url>/console/admin/api/v2/nodes

This API call will return a response containing details about the REST proxies configured in your instance.

For more details about the console API refer to following documentation: Get Node List.

Response Details

In the response, locate the section labeled RESTProxies, where you will find the corresponding RestProxyId. The structure of the response will include various attributes associated with each REST proxy node.

"RESTProxies": [
        {
            "status": "up",
            "extInfo": [],
            "displayName": "restproxy",
            "RESTProxyId": "48021a2c-e62b-40bd-b7ca-71dda883521d-restproxy",
            "url": "https://fibank3-oabcs1-hyd.blockchain.ocp.oraclecloud.com:7443/restproxy",
            "mspId": "FIBank3"
        }
    ]

Deploy the Chaincode for the Wholesale CBDC Sample Application

You can now create a channel and deploy the sample application chaincode to it.

Create a channel.
1. Define a new channel with the necessary participants as per your organisational requirements.
2. During the channel creation process, ensure Enable Rich History is selected. This option activates the rich history feature, which was previously configured.
Deploy the chaincode.
Deploy the wholesale CBDC chaincode provided in the wholesale CBDC chaincode package to the newly created channel. For details on how to deploy chaincodes, refer to Typical Workflow to Deploy Chaincodes.
Use the wholesale CBDC Postman collection provided in the wholesale CBDC chaincode package to invoke the init API. This step completes the initialization process, ensuring the chaincode is ready for use.
See Wholesale CBDC Chaincode Package.
Check the replication status.
1. Go to the Channels tab.
2. Locate the channel and click on the More Actions menu on the right side of the channel entry.
3. Select Rich History Status to view the replication status.
  - If the status is REPLICATING, it indicates that the channel data is actively replicating to the rich history database.
  - If the replication status is USER_DISABLED perform the following actions:
    1. Restart the Peer: Restart the peer node associated with the channel.
    2. Invoke a Transaction: Trigger any transaction on the channel to initiate data replication.
    3. Recheck the replication status to confirm that the data is now replicating to the rich history database.

Note the channel name and chaincode name - you'll need to configure Visual Builder with these in order to work with the sample application.

Create Rich History Database Views

After you've created the rich history database for your Oracle Blockchain Platform instance, you can run the Database View Creation script to create the views in the rich history database and generate the ORDS endpoint.

The Oracle REST Data Services (ORDS) script is a Node.js application written in TypeScript, designed to expose ORDS endpoints for retrieving account transaction details from the rich history database. It creates a RESTful endpoint that allows users to fetch chaincode transaction data (for both TypeScript and Go chaincodes) from the rich history database. In addition, it provides essential credentials - such as the ORDS endpoint, clientId, clientSecret, and Bearer token - to authenticate and access the endpoint.

Download the Database View Creation script.
1. Open the Oracle Blockchain Platform console.
2. Go to the Digital Assets tab.
3. In the left sidebar, go to the Wholesale CBDC application.
4. Download the script from the Oracle Database View Definitions for WholesaleCBDC area.
After downloading the script, refer to Oracle Database View Definitions for Wholesale CBDC for details on how to execute it.
When running the script, you will be prompted with a question: select TypeScript (TS) as the language, since the wholesale CBDC chaincode is written in TypeScript.

The script returns the ORDS endpoint, client ID and client secret.

{
  ORDSEndpoint: 'https://<base_URL>ords/<user_name|alias>/<resource_link>',
  clientId: '<clientId>',
  clientSecret: '<clientSecret>',
  bearerToken: {
    access_token: '<BearerToken>',
    token_type: 'bearer',
    expires_in: 3600
  }
}

The ORDS endpoint for accessing RESTful services follows this structure:

ORDS_REST_BASE_URL/ords/ALIAS_NAME/BASE_PATH/PATTERN

ORDS_REST_BASE_URL: The base URL of the ORDS service.
ALIAS_NAME: The database or schema alias configured in ORDS.
BASE_PATH: The base path for the RESTful services.
PATTERN: The specific endpoint pattern for the RESTful service.

To generate a bearer token for authentication, use the OAuth2 token endpoint:

ORDS_REST_BASE_URL/ords/ALIAS_NAME/oauth/token

The following parameters related to ORDS must be updated in the backend of Visual Builder to retrieve data from the rich history database. This will be completed later in Configure Visual Builder Backends.

clientId
clientSecret
ORDS endpoint
OAuth base URL: ORDS_REST_BASE_URL/ords/<userName|aliasName>