Registry API examples

This document contains examples on how to use the Registry Utility API in practice. It is not intended to be an extensive guide, but rather a starting point for developers to get familiar with the API.

Prerequisites

  1. A running validator node connected to one of DevNet, TestNet, or MainNet

  2. The Utility DARs installed on your validator node

  3. A valid business user token (<user-token>) obtained from the IAM of the validator node

  4. A business user and associated party (<user-party>) created through the Validator API

  5. The JSON API endpoint (<http-json-api>) of the participant node

  6. curl and jq installed on your system

Set environment variables

export HTTP_JSON_API=<http-json-api>
export USER_TOKEN=<user-token>

cURL Examples

Note: The JSON API in Canton 3 does not have query support as it did in Canton 2. Because of this, filtering must be done on the client side. Instead, it is recommended to use the PQS for such scenarios.

Query all assets a registrar has in custody

The example below retrieves all Holdings for a specific registrar.

Set the REGISTRAR environment variables to the registrar you want to query assets for. We assume that the token you configured has readAs rights for this party.

(
  curl \
    --url "${HTTP_JSON_API}/v1/query" \
    --header "Authorization: Bearer ${USER_TOKEN}" \
    --header "Content-Type: application/json" \
    --request POST \
    --data @- <<EOF
{
  "templateIds" : ["#utility-registry-holding-v0:Utility.Registry.Holding.V0.Holding:Holding"]
}
EOF
) | jq '
  if has("errors") then .
  else { result: [.result[] | select(
    .payload.registrar == "'"${REGISTRAR}"'"
  )] }
  end
  '

Query all assets a party holds for a specific instrument

The example below retrieves all holdings that the given party holds for a specific instrument at the given registrar.

Variables

Variable

Description

HOLDER

The party id of the holder whose assets you want to query.

INSTRUMENT_ID

The identifier of the specific instrument you want to query holdings for.

REGISTRAR

The party id of the instrument’s registrar you.

 
(
  curl \
    --url "${HTTP_JSON_API}/v1/query" \
    --header "Authorization: Bearer ${USER_TOKEN}" \
    --header "Content-Type: application/json" \
    --request POST \
    --data @- <<EOF
{
  "templateIds" : ["#utility-registry-holding-v0:Utility.Registry.Holding.V0.Holding:Holding"]
}
EOF
) | jq '
  if has("errors") then .
  else { result: [.result[] | select(
         .payload.owner == "'"${HOLDER}"'"
     and .payload.instrument.id == "'"${INSTRUMENT_ID}"'"
     and .payload.registrar == "'"${REGISTRAR}"'"
     and .payload.instrument.scheme == "RegistrarInternalScheme"
  )] }
  end
  '

Mint

Please, consult the documentation on the Mint workflow for details.

For the following example you should get two user tokens, one for the holder and one for the registrar.

Set the PACKAGE_ID to the utility-registry-app-v0-0.1.0 id from DAR Package Versions, the HOLDER_SERVICE_CID to the contract id of the holder service, and the REGISTRAR to the registrar party id.

The following example exercises the HolderService_RequestMint choice of the HolderService contract, and in case of success, returns the mintRequestCid.

(
  curl \
    --url "${HTTP_JSON_API}/v1/exercise" \
    --header "Authorization: Bearer ${HOLDER_USER_TOKEN}" \
    --header "Content-Type: application/json" \
    --request POST \
    --data @- <<EOF
{
    "templateId": "${PACKAGE_ID}:Utility.Registry.App.V0.Service.Holder:HolderService",
    "contractId": "<Contract ID of the holder service.>",
    "choice": "HolderService_RequestMint",
    "argument": {
        "registrar": "${REGISTRAR}",
        "instrumentIdentifier": {
            "source": "<Party id of the entity that originally created or issued the identifier.>",
            "id": "<The identifier for the instrument.>",
            "scheme": "<The scheme or standard used for the identifier.>"
        },
        "amount": 100,
        "reference": "<Reference for the mint.>",
        "batch": {
          "id": "<A unique identifier for the batch.>",
          "size": 1,
          "settlementFrom": "<Optional, ISO 8601 timestamp format.>",
          "settlementUntil": "<Optional, ISO 8601 timestamp format.>"
        },
        "holdingLabel": "<Label of the holding.>"
    }
}
EOF
) | jq '
  if has("errors") then .
  else .result.exerciseResult.mintRequestCid
  end
  '

If the request was successful, use the returned mintRequestCid for the cid in argument in the following example. Pay attention to the authorization token, it should be the token of the registrar.

 (
    curl \
      --url "${HTTP_JSON_API}/v1/exercise" \
      --header "Authorization: Bearer ${USER_TOKEN}" \
      --header "Content-Type: application/json" \
      --request POST \
      --data @- <<EOF
{
    "templateId": "${PACKAGE_ID}:Utility.Registry.App.V0.Service.Registrar:RegistrarService",
    "contractId": "<Contract ID of the registrar service.>",
    "choice": "RegistrarService_AcceptMintRequest",
    "argument": {
        "cid": "<The mint request contract id from the previous request.>",
        "payload": {}
    }
}
EOF
) | jq '
  if has("errors") then .
  else .result.exerciseResult.acceptedMintCid
  end
  '

The mint is now complete and you should see the minted asset.

Burn

Please, consult the documentation on the Burn workflow for details.

For the following example you should get two user tokens, one for the holder and one for the registrar.

Set the PACKAGE_ID to the utility-registry-app-v0-0.1.0 id from DAR Package Versions, the HOLDER_SERVICE_CID to the contract id of the holder service, and the REGISTRAR to the registrar party id.

The following example exercises the HolderService_RequestBurn choice of the HolderService contract, and in case of success, returns the burnRequestCid.

(
  curl \
    --url "${HTTP_JSON_API}/v1/exercise" \
    --header "Authorization: Bearer ${HOLDER_USER_TOKEN}" \
    --header "Content-Type: application/json" \
    --request POST \
    --data @- <<EOF
{
    "templateId": "${PACKAGE_ID}:Utility.Registry.App.V0.Service.Holder:HolderService",
    "contractId": "<Contract ID of the holder service.>",
    "choice": "HolderService_RequestBurn",
    "argument": {
        "registrar": "${REGISTRAR}",
        "instrumentIdentifier": {
            "source": "<Party id of the entity that originally created or issued the identifier.>",
            "id": "<The identifier for the instrument.>",
            "scheme": "<The scheme or standard used for the identifier.>"
        },
        "amount": 100,
        "reference": "<Reference for the burn.>",
        "holdingLabel": "<Label of the holding.>"
    }
}
EOF
) | jq '
  if has("errors") then .
  else .result.exerciseResult.burnRequestCid
  end
  '

If the request was successful, use the returned burnRequestCid for the cid in argument in the following example. Pay attention to the authorization token, it should be the token of the registrar.

(
    curl \
    --url "${HTTP_JSON_API}/v1/exercise" \
    --header "Authorization: Bearer ${USER_TOKEN}" \
    --header "Content-Type: application/json" \
    --request POST \
    --data @- <<EOF
{
    "templateId": "${PACKAGE_ID}:Utility.Registry.App.V0.Service.Registrar:RegistrarService",
    "contractId": "<Contract ID of the registrar service.>",
    "choice": "RegistrarService_AcceptBurnRequest",
    "argument": {
        "cid": "<The burn request contract id from the previous request.>",
        "payload": {}
    }
}
EOF
) | jq '
  if has("errors") then .
  else .result.exerciseResult.acceptedBurnCid
  end
  '

The burn is now complete and you should see the burned asset.

Transfer

Please, consult the documentation on the Transfer workflow for details. For the following example you should get two user tokens, one for each holder who participates in the transfer.

(
  curl \
    --url "${HTTP_JSON_API}/v1/exercise" \
    --header "Authorization: Bearer ${SENDER_USER_TOKEN}" \
    --header "Content-Type: application/json" \
    --request POST \
    --data @- <<EOF
{
    "templateId": "${PACKAGE_ID}:Utility.Registry.App.V0.Service.Holder:HolderService",
    "contractId": "<Contract ID of the sender's holder service.>",
    "choice": "HolderService_OfferTransfer",
    "argument": {
        "registrar": "${REGISTRAR}",
        "receiver": "<Party id of the receiver.>",
        "instrumentIdentifier": {
            "source": "<Party id of the entity that originally created or issued the identifier.>",
            "id": "<The identifier for the instrument.>",
            "scheme": "<The scheme or standard used for the identifier.>"
        },
        "amount": 100,
        "reference": "<Reference for the transfer.>",
        "senderLabel": "<Label of the holding to send.>",
        "batch": {
          "id": "<A unique identifier for the batch.>",
          "size": 1,
          "settlementFrom": "<Optional, ISO 8601 timestamp format.>",
          "settlementUntil": "<Optional, ISO 8601 timestamp format.>"
        }
    }
}
EOF
) | jq '
  if has("errors") then .
  else .result.exerciseResult.transferRequestCid
  end
  '

If the request was successful, use the returned transferRequestCid for the cid in argument in the following example. Pay attention to the authorization token, it should be the token of the receiver.

(
    curl \
    --url "${HTTP_JSON_API}/v1/exercise" \
    --header "Authorization: Bearer ${RECEIVER_USER_TOKEN}" \
    --header "Content-Type: application/json" \
    --request POST \
    --data @- <<EOF
{
    "templateId": "${PACKAGE_ID}:Utility.Registry.App.V0.Service.Holder:HolderService",
    "contractId": "<Contract ID of the receiver's holder service.>",
    "choice": "HolderService_AcceptTransferOffer",
    "argument": {
        "cid": "<The transfer request contract id from the previous request.>",
        "payload": {
            "receiverLabel": "<Label of the holding to receive.>"
        }
    }
}
EOF
) | jq '
  if has("errors") then .
  else .result.exerciseResult.acceptedTransferCid
  end
  '

The transfer is now complete. Keep in mind though, that an accepted transfer does not necessarily mean the transfer has actually occurred. Automations behind the scenes deal with accepted transfers, and the transfer may fail if the conditions are not met.