Wholesale CBDC Deployment Reference

The following information includes descriptions of the database objects that are created by the ORDS script, and troubleshooting tips.

The ORDS script creates the following operational views using the configured VIEW_PREFIX parameter. 

<VIEW_PREFIX>_ACCOUNTS_V
<VIEW_PREFIX>_TRANSFER_EVENTS_V
<VIEW_PREFIX>_HOLDS_V
<VIEW_PREFIX>_ACTIVE_ROLES_V
<VIEW_PREFIX>_ACCOUNT_TX_HISTORY_V
<VIEW_PREFIX>_ACCOUNT_HISTORY_V

If you select analytics, the following analytics views are created, scoped to the deployment.

<VIEW_PREFIX>_ACCOUNTS_MOD
<VIEW_PREFIX>_TRANSACTION_MOD
<VIEW_PREFIX>_ACCOUNTS_TRANSACTION_MOD

The script also creates or configures the ORDS module, routes, schema alias, role, privilege, OAuth client, and client-role association using the configured values.

View Catalog and Query Logic

The following views are ordinary Oracle views in the selected schema; they do not modify the extractor tables.

View Primary Source Purpose/Logic
<VIEW_PREFIX>_ACCOUNTS_V _more, _store_state Builds the current account directory from createAccount calls and account/token state. It resolves account, user and organization identity, balances, hold balances, status, daily limits, token metadata, and creation transaction metadata.
<VIEW_PREFIX>_TRANSFER_EVENTS_V _more Normalizes token receipt logs into transfer-event rows. It extracts sender, receiver, amount, function, block/transaction metadata, and optional ~OBPRPCTX~.value.category context.
<VIEW_PREFIX>_HOLDS_V _store_hist, _more, _store_state Reconstructs mint, burn, and transfer-hold records. It extracts operation/holding ID, accounts, notary, amount, expiry, token, category, description, and the latest lifecycle status. It also provides fallback rows when a current state row is not resolvable.
<VIEW_PREFIX>_ACTIVE_ROLES_V _more Applies role add/remove history and returns the latest active role assignment per account and role.
<VIEW_PREFIX>_ACCOUNT_TX_HISTORY_V The preceding operational views Produces account-facing transaction-history rows, including both sides of transfers and normalized mint/burn/hold lifecycle outcomes. It enriches from/to identities from the _ACCOUNTS_V view.
<VIEW_PREFIX>_ACCOUNT_HISTORY_V _more, _ACCOUNTS_V Produces account configuration history from account contract mutations, including daily limit revisions, timestamps, block numbers, and transaction IDs.
<VIEW_PREFIX>_ACCOUNTS_MOD (optional analytics) _ACCOUNTS_V Exposes account metadata in the analytics-compatible account shape.
<VIEW_PREFIX>_TRANSACTION_MOD (optional analytics) _TRANSFER_EVENTS_V, _HOLDS_V, _store_hist Exposes normalized business transactions, including transfer, mint, burn, request, hold, release, and resulting balances where available.
<VIEW_PREFIX>_ACCOUNTS_TRANSACTION_MOD (optional analytics) _TRANSACTION_MOD, _ACCOUNTS_V Adds source and destination organization context to analytics transaction records.

ORDS Routes

All routes are GET routes under <BASE_PATH>/ and require an OAuth bearer token. ORDS returns a collection envelope; an empty items array with HTTP 200 means that the request was valid but had no matching indexed records.

Route Use and Response Behavior Required Inputs Optional Inputs and Default Behavior
getCBDCTransactionById Returns one normalized ledger-transaction detail record. token_id identifies the WCBDC token; transaction_id is the Besu transaction hash/identifier to retrieve. None. No matching transaction returns an empty collection.
getCBDCAccountTransactionHistoryWithFilters Returns history for the account identified by its business identity. token_id identifies the token; org_id identifies the organization; user_id identifies the account user. startTime and endTime restrict the time range; omitted means no lower/upper time boundary. bookmark is the zero-based offset; omitted means 0. pageSize is the number of rows requested; omitted uses the handler default.
getAllCBDCAccountTransactionHistoryWithFilters Returns token-wide account transaction history. token_id identifies the token. startTime, endTime, bookmark, and pageSize behave as for the account-specific history route.
getCBDCAccountStatusHistory Returns indexed status-history rows for a business account. token_id, org_id, and user_id identify the account. None. No matching account/history returns an empty collection.
getApproverActionHistory Returns mint/burn decisions and final transfer-hold actions. executeHold is executed; releaseHold is rejected. token_id limits results to the token. caller_account_id is the manager/approver wallet address. Omit it to return actions by all actors; provide it to return only that wallet's actions. It is a data-scope filter, not authorization.
getTokenHistory Returns token-level history and supply-related information. token_id identifies the token. None.
getCBDCAccountsByRole Returns accounts associated with a role. role is the role name to match. None; the result is not token-filtered by this route.
getUsersByRole Returns user/account role assignments for a role. role is the role name to match. None.
getOrgAccountsByRole Returns accounts in one organization that have a role org_id identifies the organization; role is the role name. None.
getAllCBDCAccounts Returns all indexed accounts for one token. token_id identifies the token. None.
getAllActiveCBDCAccounts Returns indexed accounts whose current status is active. token_id identifies the token. None.
getAllSuspendedCBDCAccounts Returns indexed accounts whose current status is suspended. token_id identifies the token. None.
getAllOrgAccounts Returns all indexed accounts in one organization. org_id identifies the organization. None; the result is not token-filtered by this route.
getPendingCBDCIssuance Returns current pending transfer-hold operations only; terminal, executed, rejected, and released operations are excluded. token_id identifies the token. caller_account_id is the notary/manager wallet. Omit it for the full pending queue; provide it to return only holds assigned to that wallet.
getPendingCBDCRequest Returns current pending mint/burn requests only. token_id identifies the token; request_type selects the supported request type, such as mint or burn. None. Approved or rejected requests are excluded.
getPendingRequest Compatibility route for the same pending-request use case. token_id and request_type have the same meaning as getPendingCBDCRequest None.
getCBDCAccountsByUser Returns account records for one organization/user/token combination. token_id, org_id, and user_id identify the account owner and token. None.
getCBDCAccountHistory Returns account configuration/history revisions. account_address is the blockchain account/wallet address. offset is the zero-based row offset; omit for the first page. limit is the maximum row count; omit to use the SQL handler default.
getCBDCAccountStatus Returns the current indexed account status. token_id, org_id, and user_id identify the account. None.
getRolesByAccount Returns roles for a resolved account. token_id is always required. Supply either account_address (the blockchain account/wallet address), or the combined org_id and user_id business lookup. If account_address is supplied it is the direct account filter; otherwise the route uses org_id and user_id. If neither lookup resolves an account, the response is empty.
getAllRegisteredOrgs Returns organizations represented by indexed accounts for a token. token_id identifies the token. None.
getCBDCMetadata Returns indexed immutable token metadata. token_id identifies the token. None.
getCBDCRetiredQuantity Returns retired/burned quantity information for a token. token_id identifies the token. None.

Pagination and timestamps: For the two history routes that support the bookmark and pageSize parameters, the bookmark parameter is a zero-based row offset and the pageSize parameter is camel case. Omit either value to use the handler default. The startTime and endTime parameters, when supplied, use ISO-8601 timestamp text in the format YYYY-MM-DDTHH:MI:SS+/-HH:MI.

Endpoint inventory: The exact route inventory belongs to the script version packaged for the deployment. After the run, use the ORDS OpenAPI catalog or the generated endpoint output as the authoritative list for the client application.

Troubleshooting

Message or Condition Resolution
NJS-516: no configuration directory set A TNS alias was used without an accessible wallet/configuration directory. Extract the wallet and configure the Oracle client so that the tnsnames.ora file is available.
NJS-511 or ORA-12506 Listener, endpoint, service name, network allowlist, or wallet configuration issue. Validate the Oracle connection outside the script with the DBA.
OAuth token request returns 404 Verify the exact alias in /ords/<ALIAS_NAME>/oauth/token. The alias is not necessarily the Oracle username.
Endpoint returns 401 Obtain a fresh token and verify the OAuth client has the role/privilege associated with the configured module base path.
Endpoint returns 404 Verify host, alias, base path, route name, and that the module is published.
ORDS-25001 The endpoint reached ORDS but its SQL failed. Verify the table prefix, contract addresses, source data shape, and required request parameters.
ORA-20049: Cannot alter the URL mapping while the schema is enabled The chosen ALIAS_NAME conflicts with an enabled schema mapping. Reuse the schema's existing alias, or have the ORDS administrator complete the approved disable/remap/enable procedure before running the script again.
Views contain no rows Confirm the correct rich history profile was selected during instance creation, the table prefix is exact, contract addresses match the deployed proxies, and transactions have been indexed.
Objects conflict with another deployment Use a distinct VIEW_PREFIX, module name, base path, role, privilege, OAuth client name, and alias.