Registry API examples
*********************

This document contains examples on how to use the :doc:`Registry Utility API
<../../registry-user-guide/index>` 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
=============

#. A running validator node connected to one of DevNet, TestNet, or MainNet
#. The Utility DARs installed on your validator node
#. A valid business user token (``<user-token>``) obtained from the IAM of the validator node
#. A business user and associated party (``<user-party>``) created through the Validator API
#. The JSON API endpoint (``<http-json-api>``) of the participant node
#. ``curl`` and ``jq`` installed on your system

Set environment variables
-------------------------

.. code-block:: shell

    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 :doc:`Holdings
<../../registry-holding-model/Utility-Registry-Holding-V0-Holding>` 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.

.. code-block:: shell

    (
      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.

.. list-table:: Variables
  :header-rows: 1

  * - 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.

.. code-block:: shell

    (
      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 :doc:`Mint workflow <../../registry-user-guide/workflows>`
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 :doc:`../../dar-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``.

.. code-block:: shell

    (
      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.

.. code-block:: shell

     (
        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 :doc:`Burn workflow <../../registry-user-guide/workflows>`
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 :doc:`../../dar-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``.

.. code-block:: shell

    (
      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.

.. code-block:: shell

    (
        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 :doc:`Transfer workflow
<../../registry-user-guide/workflows>` for details. For the following example you should get **two**
user tokens, one for each holder who participates in the transfer.

.. code-block:: shell

    (
      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.

.. code-block:: shell

    (
        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.

.. Links:
.. _jq: https://stedolan.github.io/jq/
.. _Canton 2: https://docs.daml.com/json-api/index.html#get-all-active-contracts-matching-a-given-query
.. _PQS: https://docs.daml.com/query/pqs-user-guide.html