Prepaid Oracle User Guide

This guide provides step-by-step instructions for creating data requests to an external data provider API using the Prepaid Oracle system on the Canton blockchain.

This document focuses on the request creation process using direct requests to the Canton JSON API.

Overview

The Prepaid Oracle system enables secure, paid requests for off-chain data through the Canton blockchain. The request creation process involves:

1. Preparing request parameters: Gather and format the request payload.

2. Retrieving contracts: Get the current Amulet rules and open mining round contracts.

3. Exercising a contract choice: Submit a transaction that creates a paid data request.

The oracle then processes the request off-chain (including payment settlement) and posts the response back on-ledger.

Prerequisites

Required information

You need the following information before starting:

• Canton participant endpoint: URL of your Canton participant JSON API

• Canton authentication token: Valid token for API access

• Consumer party ID: Your party identifier in Canton (e.g., Consumer::1220...)

• RequestFactory contract ID: Contract ID for the request factory

• DSO party ID: DSO party identifier

• Data provider details (provider-dependent): Data request payload (stringified JSON)

• Amulet contract ID: An Amulet contract to fund payment

• Payment locked amount: Amount to lock for the request

Environment setup

Ensure you have:

• A Canton node connected to the same domain as the oracle node

• The Prepaid Oracle DAR uploaded to your Canton node

• Sufficient Amulet balance for the request

Creating a Data Request

Prepare provider request parameters

Prepare the provider request payload as valid JSON, then stringify it (single-line JSON string).

Below is an example shape for a provider request payload. The exact schema depends on your data provider.

{
  "start_time": "2023-01-01T00:00:00Z",
  "end_time": "2023-01-01T23:59:59Z",
  "sort": "desc",
  "page_size": 4,
  "interval": "1h",
  "include_exchanges": None,
}

When sending the request to Canton, you will pass a stringified version of the JSON (quotes escaped, no unescaped newlines). Example:

{\"start_time\":\"2023-01-01T00:00:00Z\",\"end_time\":\"2023-01-01T23:59:59Z\",\"sort\":\"desc\",\"page_size\":4,\"interval\":\"1h\",\"include_exchanges\":null}

Required parameters

The CreateRequest choice expects the following parameters:

• dataRequest → Stringified provider request payload (stringified JSON)

• lockedAmount → Amount to lock for payment

• dso → The DSO party

• amuletRulesCid → Current Amulet rules contract ID

• openRoundCid → Current OpenMiningRound contract ID

• inputs → A list of Amulets owned by your consumer party (typically one is enough)

Note: Parameter names are part of the on-ledger template interface. Even when switching data providers, the workflow stays the same; only the meaning/content of provider-specific fields (like catalog, dataRequest, and credentials) changes.

Submit the request creation transaction

Make a POST request to Canton to exercise the CreateRequest choice.

Request

POST {PARTICIPANT_NODE_JSON_API_URL}/v2/commands/submit-and-wait-for-transaction-tree
Authorization: Bearer {CANTON_TOKEN}
Content-Type: application/json

Request body

{
  "actAs": ["{YOUR_CONSUMER_PARTY}"],
  "commandId": "create-request-1",
  "commands": [
    {
      "actAs": ["{YOUR_CONSUMER_PARTY}"],
      "commandId": "create-request-1",
      "ExerciseCommand": {
        "contractId": "{REQUEST_FACTORY_CONTRACT_ID}",
        "templateId": "{PACKAGE_ID}:PrepaidOracle.RequestFactory:RequestFactory",
        "choice": "CreateRequest",
        "choiceArgument": {
          "dso": "{DSO_PARTY}",
          "amuletRulesCid": "{AMULET_RULES_CONTRACT_ID}",
          "openRoundCid": "{OPEN_ROUND_CONTRACT_ID}",
          "inputs": [{
              "tag": "InputAmulet",
              "value": "{YOUR_AMULET_CONTRACT_ID}"
           }],
          "dataRequest": "{STRINGIFIED_PROVIDER_DATA_REQUEST}",
          "clientId": "{YOUR_PROVIDER_CLIENT_ID}",
          "clientSecret": "{YOUR_PROVIDER_CLIENT_SECRET}",
          "lockedAmount": {PAYMENT_LOCKED_AMOUNT}
        }
      }
    }
  ],
  "disclosedContracts": [
    {
      "templateId": "{AMULET_PACKAGE_ID}:Splice.AmuletRules:AmuletRules",
      "contractId": "{AMULET_RULES_CONTRACT_ID}",
      "synchronizerId": "{GLOBAL_DOMAIN_SYNCHRONIZER_ID}",
      "createdEventBlob": "{AMULET_RULES_DISCLOSED_BLOB}"
    },
    {
      "templateId": "{AMULET_PACKAGE_ID}:Splice.Round:OpenMiningRound",
      "contractId": "{OPEN_ROUND_CONTRACT_ID}",
      "synchronizerId": "{GLOBAL_DOMAIN_SYNCHRONIZER_ID}",
      "createdEventBlob": "{OPEN_ROUND_DISCLOSED_BLOB}"
    }
  ]
}

Troubleshooting

A request can fail. In this case, the Request contract is archived and a FailedRequest is created. Common failure scenarios include:

Locked amount does not cover service amount

Cause: The lockedAmount you specified is less than the service fee charged by the oracle.

Solution: Increase lockedAmount and ensure you have sufficient Amulet balance.

Stringified JSON request data is not valid

Cause: dataRequest is not a properly stringified JSON string.

Solution: Validate and re-stringify your JSON:

• Validate the JSON before stringifying.

• Ensure all quotes are properly escaped.

• Ensure newlines are removed or escaped (recommended: remove).

• Test the final string with a JSON parser (it must parse as a JSON string whose content is valid JSON when decoded).

Provider returns an error when sending the request

Cause: The provider API returned an error when processing your request.

Solution: Check:

• Request payload format and required fields for the provider schema.

• Requested data is supported and you have permission.

• Rate limits / throttling conditions.

• Provider documentation for error codes and request schema.

Reading the FilledRequest

Request processing (what the oracle does)

After your request is created on-ledger, the oracle typically:

A FilledRequest contract will have fields similar to:

• Detects your new request

• Proceeds to payment by unlocking your Amulet, taking the service amount needed, and returning any remaining amount to the consumer party

• Reads the Request contract

• Makes the request to the data provider on your behalf

• Updates the Request contract with status PENDING

• Waits for the provider’s response to be available

• Archives the pending Request and writes the response data into a FilledRequest

A FilledRequest contract will have fields similar to:

{
  "oracle": "{ORACLE_PARTY}",
  "consumer": "{CONSUMER_PARTY}",
  "catalog": "{CATALOG_ID}",
  "requestData": "{stringified json request data}",
  "responseData": "{stringified json response data}",
  "serviceAmountCharged": "1.0000000000"
}

Read the FilledRequest contract

Once the oracle has processed your request and received a response, a FilledRequest contract is created. To retrieve it, query active contracts on the Canton ledger.

Query for FilledRequest contracts

Request

POST {PARTICIPANT_NODE_JSON_API_URL}/v2/state/active-contracts
Authorization: Bearer {CANTON_TOKEN}
Content-Type: application/json

Request body

{
  "activeAtOffset": {offset},
  "verbose": false,
  "eventFormat": {
    "filtersByParty": {
      "{YOUR_CONSUMER_PARTY}": {
        "cumulative": [
          {
            "identifierFilter": {
              "TemplateFilter": {
                "value": {
                  "includeCreatedEventBlob": false,
                  "templateId": "{PACKAGE_ID}:PrepaidOracle.Request:FilledRequest"
                }
              }
            }
          }
        ]
      }
    },
    "verbose": false
  }
}

Expected response (example)

[
  {
    "workflowId": "",
    "contractEntry": {
      "JsActiveContract": {
        "createdEvent": {
          "offset": 627962,
          "nodeId": 1,
          "contractId": "{FILLED_REQUEST_CONTRACT_ID}",
          "templateId": "{PACKAGE_ID}:PrepaidOracle.Request:FilledRequest",
          "contractKey": null,
          "createArgument": {
            "oracle": "{ORACLE_PARTY}",
            "consumer": "{YOUR_CONSUMER_PARTY}",
            "requestData": "{stringified json request data}",
            "responseData": "{stringified json response data}",
            "serviceAmountCharged": "1.0000000000"
          },
          "createdEventBlob": "",
          "interfaceViews": [],
          "witnessParties": ["{ORACLE_PARTY}"],
          "signatories": ["{ORACLE_PARTY}"],
          "observers": ["{YOUR_CONSUMER_PARTY}"],
          "createdAt": "2026-01-23T14:56:45.708037Z",
          "packageName": "prepaid-oracle",
          "representativePackageId": "{PACKAGE_ID}",
          "acsDelta": true
        },
        "synchronizerId": "global-domain::1220...",
        "reassignmentCounter": 0
      }
    }
  }
]

Understanding the FilledRequest fields

In createArgument, the key fields are:

• oracle → The oracle party that processed the request

• consumer → Your consumer party ID

• requestData → The original request payload you submitted (stringified JSON)

• responseData → The provider response payload (stringified JSON)

• serviceAmountCharged → The actual service fee charged by the oracle

Service amount: serviceAmountCharged shows the fee deducted from your locked amount. Any remaining amount from lockedAmount is returned to you.