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 must be implemented:

System Owner Groups: Assign the single combined system owner IDCS group (containing all of the system owner personas) to the REST_CLIENT application role of the system owner Oracle Blockchain Platform Digital Assets Edition instance. Do not assign individual persona-specific groups directly to the Oracle Blockchain Platform Digital Assets Edition instance.
Participant Organization Groups: For each participant organization, assign the single combined participant organization IDCS group (containing all of the persona-specific groups for that organization) to the REST_CLIENT application role of the respective Oracle Blockchain Platform Digital Assets Edition instance.
Administrative Roles: Assign the relevant administrative groups, such as System_Admins and Org1_Admins, to the ADMIN application role of their respective Oracle Blockchain Platform Digital Assets Edition instance.

This configuration ensures that both System Owner and Participating Organization 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 page 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 used by Visual Builder. You'll need to update these parameters in Visual Builder later as described in Configure Visual Builder Backends.

Complete the following steps 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 Blockchain Platform.

In generic mode, configure the single instance of Oracle Autonomous Database for the system owner instance of Oracle Blockchain Platform. In confidential mode, you must configure each participant organization and the system owner with separate instances of Oracle Autonomous Database.

Open the Oracle Blockchain Platform console for the network instance.
Click 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 System_Admins and Org_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 in Oracle Blockchain Platform.

The wholesale CBDC application manages the creation of enrollments for users during account setup; however, when a system administrator 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 System_Admins group.

When setting up accounts, enrollments are created for the respective organizations. For instance, when accounts for the system owner are established, corresponding enrollments will be generated. However, if any participant organization accounts are created through the system administrator page, enrollments will not be automatically created for those organizations. In this wholesale CBDC workflow, you must set up organization administrator accounts on the system administrator page. Therefore, you must manually create enrollments for the organization administrator 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 value will be used 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, you must call the Oracle Blockchain Platform console APIs using an administrative user account. Authentication can be done by using 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 <oracleblockchainplatform_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-40cd-b7ca-71dda883521d-restproxy",
            "url": "https://bank3-oabcs1-hyd.blockchain.ocp.oraclecloud.com:7443/restproxy",
            "mspId": "Bank3"
        }
    ]

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 according to your organizational requirements.
2. During the channel creation process, ensure Enable Rich History is selected. This option activates the rich history feature, which was previously configured.
3. Confidential mode only: For Private Data Collections, enter an asterisk (*) to allow access to all private data collections.
  If you do not complete this step, the data returned from the private data collection will not be accurate.
4. Confidential mode only: Repeat the previous two steps (enabling rich history and access to private data collections on the previously created channel) for all other participant organizations in the network.
Deploy the chaincode.
- Generic mode: Deploy the wholesale CBDC chaincode by downloading the wholesale CBDC chaincode package and deploying the archive file inside it (WholesaleCBDC.zip) to the new channel. The package name is Wholesale CBDC.
- Confidential mode: Deploy the confidential wholesale CBDC chaincode by downloading the confidential wholesale CBDC chaincode package and deploying the archive file inside it (WholesaleCBDC-Confidential.zip) to the new channel. The package name is WholesaleCBDCConfidential.
For details on how to deploy chaincodes, refer to Typical Workflow to Deploy Chaincodes.
Call the init API, using either the wholesale CBDC Postman collection provided in the wholesale CBDC chaincode package or the confidential wholesale CBDC Postman collection in the confidential wholesale CBDC chaincode package as appropriate. This step completes the initialization process, ensuring that the chaincode is ready for use.
See Wholesale CBDC Chaincode Package or Confidential Wholesale CBDC Chaincode Package.
Check the replication status.
1. Go to the Channels tab.
2. Locate the channel and click 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, the channel data is actively replicating to the rich history database.
  - If the replication status is USER_DISABLED, complete the following actions:
    1. Restart the peer: Restart the peer node associated with the channel.
    2. Start 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 lets users fetch chaincode transaction data (for both TypeScript and Go chaincodes) from the rich history database. It also 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 page.
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 run it.

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

In generic mode, all organizations use a single ORDS endpoint configuration. The script returns endpoints for accounts at three scopes: individual accounts, organization-level accounts, and all accounts.

{
  ORDSEndpoint: 'https://<base_URL>ords/<user_name|alias>/<resource_link>',
 {
  "ORDSEndpoint": {
    "Accounts": "https://<base_URL>ords/ALIAS_NAME/BASE_PATH/PATTERN",
    "OrgAccounts": "https://<base_URL>ords/ALIAS_NAME/BASE_PATH/PATTERNOrgAccounts",
    "AllAccounts": "https://<base_URL>ords/ALIAS_NAME/BASE_PATH/PATTERNAllAccounts"
  },
  clientId: '<clientId>',
  clientSecret: '<clientSecret>',
  bearerToken: {
    access_token: '<BearerToken>',
    token_type: 'bearer',
    expires_in: 3600
  }
}

In confidential mode, every organization including the system owner has its own ORDS configuration. The system owner endpoints include access to all accounts. The participant organizations have access only to their own organization-level accounts.

System owner:

{
  ORDSEndpoint: 'https://<base_URL>ords/<user_name|alias>/<resource_link>',
 {
  "ORDSEndpoint": {
    "Accounts": "https://<base_URL>ords/ALIAS_NAME/BASE_PATH/PATTERN",
    "OrgAccounts": "https://<base_URL>ords/ALIAS_NAME/BASE_PATH/PATTERNOrgAccounts",
    "AllAccounts": "https://<base_URL>ords/ALIAS_NAME/BASE_PATH/PATTERNAllAccounts"
  },
  clientId: '<clientId>',
  clientSecret: '<clientSecret>',
  bearerToken: {
    access_token: '<BearerToken>',
    token_type: 'bearer',
    expires_in: 3600
  }
}

Participant organization:

{
  ORDSEndpoint: 'https://<base_URL>ords/<user_name|alias>/<resource_link>',
 {
  "ORDSEndpoint": {
    "Accounts": "https://<base_URL>ords/ALIAS_NAME/BASE_PATH/PATTERN",
    "OrgAccounts": "https://<base_URL>ords/ALIAS_NAME/BASE_PATH/PATTERNOrgAccounts"
  },
  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 back end 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 (Accounts endpoint only; OrgAccounts and AllAccounts endpoints are derived internally)
OAuth base URL: ORDS_REST_BASE_URL/ords/<userName|aliasName>