Enhancements to Postman Collections

Oracle Blockchain Platform Digital Assets Edition adds support for endorsement parameters, confidential chaincodes, and OAuth 2.0 to the Postman collections generated by Blockchain App Builder.

Blockchain App Builder enables you to create a Postman collection that includes example payloads for all of your chaincode controller APIs. For more information, see Generate a Postman Collection Using the CLI and Generate a Postman Collection Using Visual Studio Code.

Oracle Blockchain Platform Digital Assets Edition extends that functionality by including an additional parameter in the request payload for all setter methods. For generic (as opposed to confidential mode) chaincode, the parameter is either endorsers or sameOrgEndorser. The sameOrgEndorser parameter, if true, indicates that transaction endorsements must be from the same organization as the requester. The endorsers parameter specifies a list of peers that must endorse the transaction.

The sameOrgEndorserOptionInWrapperAPI parameter in the .ochain.json file in the chaincode specifies which APIs require a sameOrgEndorser value. APIs that are associated with the sameOrgEndorserOptionInWrapperAPI parameter have the sameOrgEndorser parameter set to true in their payloads. All other APIs include the endorsers parameter instead of the sameOrgEndorser parameter.

The following snippet shows the sameOrgEndorserOptionInWrapperAPI parameter in the .ochain.json file in the wholesale CBDC chaincode package.

"sameOrgEndorserOptionInWrapperAPI": ["addConversionRate","addTokenAdmin","addTokenAuditor","approveBurn","approveMint","burnTokens","createExchangePoolAccounts","deleteHistoricalTransactions","initializeCBDCToken","initializeExchangePoolUser","issueTokens","mintWithFundingExchangePool","rejectBurn","rejectMint","removeTokenAdmin","removeTokenAuditor","requestBurn","requestMint","updateCBDCToken","updateConversionRate"]

You can customize this parameter as needed. When the wrapper API is generated, the specified APIs will have the sameOrgEndorser parameter set to true in their payloads.

The following example payloads show these endorsement parameters.

addOrgAdmin

{
    "chaincode": "{{bc-chaincode-name}}",
    "args": [
        "addOrgAdmin",
        "{{bc-org-id}}",
        "{{bc-user-id}}"
    ],
    "timeout": {{bc-timeout}},
    "sync": {{bc-sync}},
    "endorsers": {{endorsers}}
}

addTokenAdmin

{
    "chaincode": "{{bc-chaincode-name}}",
    "args": [
        "addTokenAdmin",
        "{{bc-org-id}}",
        "{{bc-user-id}}"
    ],
    "timeout": {{bc-timeout}},
    "sync": {{bc-sync}},
    "sameOrgEndorser": true
}

Confidential Chaincode Support

Chaincodes generated in confidential mode handle parameters differently from generic mode. In confidential chaincodes, API arguments are passed by using a transient map in the request payload. This ensures that arguments remain confidential and are not exposed in logs. For more information about confidential chaincode, see Confidential Payments Overview.

All getter methods include a peer parameter (not present in generic mode chaincode).

All setter methods include the endorsers parameter, which specifies a list of peers that must endorse the transaction. The sameOrgEndorserOptionInWrapperAPI parameter in the .ochain.json file is set to an empty array:

"sameOrgEndorserOptionInWrapperAPI": []

Setter methods require a Confidential-Transaction header, which indicates that the blinding factor required for confidential transactions is retrieved from the Oracle Blockchain Platform instance. This header is required in Postman requests for confidential transactions.

To maintain the security of confidential mode chaincode, pass arguments in a transientMap object. You can pass arguments directly in the args parameter in the transient map, as shown in the following example for the activateAccount method:

"transientMap": { "args": "[\"account_id value\"]" }

For the wrapper API Postman collection only (not the generic Postman collection), you can also use the transientMapArgsFlag flag, which if set to true automatically passes all arguments to the transient map, as shown in the following example for the activateAccount method:

{
   "accountId": "account_id value",
   "transientMapArgsFlag": true
}

The following example Postman requests show these parameters and headers.

createAccount (setter method)

curl --location 'https://test-xyz-abc.blockchain.ocp.oraclecloud.com:7443/restproxy/api/v2/channels/default/transactions' \
--header 'Content-Type: application/json' \
--header 'Confidential-Transaction: true' \
--header 'Authorization: Bearer {{access_token}}' \
--data '{
    "chaincode": "{{bc-chaincode-name}}",
    "args": [
        "activateAccount"
    ],
    "timeout": 6000,
    "sync": true,
    "endorsers": ["org1-xyz-abc.blockchain.ocp.oraclecloud.com:20009", "org2-xyz-abc.blockchain.ocp.oraclecloud.com:20009"],
    "transientMap": {
        "args": "[\"account_id value\"]"
    }
}'

getAllActiveAccounts (getter method)

curl --location 'https://test-xyz-abc.blockchain.ocp.oraclecloud.com:7443/restproxy/api/v2/channels/default/chaincode-queries' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data '{
    "chaincode": "{{bc-chaincode-name}}",
    "args": [
        "getAllActiveAccounts"
    ],
    "timeout": 6000,
    "sync": true,
    "peer": "org-xyz-abc.blockchain.ocp.oraclecloud.com:20009",
    "transientMap": {
        "args": "[\"bc-org-id value\",\"bc-token-id value\"]"
    }
}'

OAuth 2.0 Support

By default, the Postman collections generated by Blockchain App Builder are configured for OAuth 2.0 authorization. You must provide the following values in the global variables of the Postman collection to enable OAuth 2.0.

client-id: The client ID of the Oracle Blockchain Platform instance.
client-secret: The client secret of the Oracle Blockchain Platform instance.
access-token-url: The access token URL contains the domain URL of the Oracle Blockchain Platform instance, in the following format: https://<domain-URL>/oauth2/v1/token

Complete the following steps to retrieve the client ID, client secret, and domain URL for an Oracle Blockchain Platform instance:

Sign in to your Oracle Cloud Infrastructure (OCI) account. Select the compartment that contains the Oracle Blockchain Platform instance.
In the console, click the Navigation menu, and then click Identity & Security.
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 your Oracle Blockchain Platform instance and open that instance's details page.
The default page displayed is the OAuth Configuration page. The Client ID and Client Secret fields are in the General Information section.
Navigate back to the Domains page and then click the domain that is used by your Oracle Blockchain Platform instance.
The domain URL is displayed in the domain details.

These global variables are used in a pre-request script to generate an access_token placeholder. The script generates a token for the bc-admin user, so that every request runs with bc-admin authorization.

The first request generates a bc-admin token using the specified credentials. The token and the expiry value are stores in Postman collection variables. Missing or expired tokens are automatically regenerated. If the client ID or client secret changes, the script automatically detects the change, invalidates the previous token and generates a token with updated credentials. If you modify the access_token value manually, it can cause requests to fail. If you clear the access_token value, the script generates another bc-admin token automatically.

You can use the Generate Access Token for User request in the Postman collection to generate and use a token other than the default bc-admin token. To generate a custom access token, complete the following steps.

Open the Generate Access Token for User request. By default, the username and password values are set to bc-admin.
Update the username and password values in the collection variables.
Click Generate New Access Token. The Manage Access Tokens window opens.
Update the default name, review the other details, and then click Save. The token is now available for use, and shown in the Available Tokens section on the Authorization page.

Generated Postman collections include variables required for OAuth 2.0 support, as shown in the following table.

Variable	Description	Default Value
`client-id`	Client ID of the Oracle Blockchain Platform instance.	`client-id` value
`client-secret`	Client Secret of the Oracle Blockchain Platform instance.	`client-secret` value
`access-token-url`	OAuth 2.0 token endpoint of the domain of the Oracle Blockchain Platform instance.	`access-token-url` value
`access_token`	OAuth 2.0 access token generated for the `bc-admin` or custom user.	Not available initially; managed by script
`access_token_expiry`	Expiry time of the generated access token.	Not available initially; managed by script
`admin_credentials_hash`	Hash value of credentials used for token validation and regeneration.	Not available initially; managed by script