Workflows

Create Instrument Configuration

In the Registry Utility, a party with the Registrar role must create an InstrumentConfiguration contract for each instrument they support. This contract establishes an identifier for the instrument and defines the credential requirements for holding, minting, and burning its tokens (Holdings):

• Holder Credential Requirements: Credentials needed for holding and transferring tokens of the instrument.

• Issuer Credential Requirements: Credentials needed for minting and burning tokens.

For each credential requirement, the following values need to be specified based on the credential model:

• Issuer: The ledger party of the issuer of the credential.

• Property: The claim’s property (e.g., “isIssuerOf” or “isHolderOf”).

• Value: The value of the claim property (e.g., the instrument’s name or a unique identifier).

By correctly configuring these values, the Registrar ensures that only authorized parties can hold, mint, or burn tokens for a specific instrument, according to its defined rules.

Once an instrument configuration is created, it gets explicitly disclosed by the operator backend. This makes it accessible to all parties interacting with the Registry Utility, ensuring that everyone has the latest information on instrument configurations and their associated credential requirements.

Mint

The registry’s Mint request workflow allows authorized parties to create tokens (Holdings) of a specific instrument. This process uses a request-accept-execute workflow to ensure that only eligible parties can initiate and approve the minting of tokens.

• Prerequisites/Credential Checks:

  • Minting requires an InstrumentConfiguration for the instrument, see the section above for creating one.

  • It is validated that the requestor has valid Instrument Issuer credentials for the instrument as defined in the InstrumentConfiguration, ensuring that only authorized parties can mint Holdings. If no Instrument Issuer credentials are specified in the InstrumentConfiguration, any party is eligible to request a mint.

• Mint Request:

  The party requesting the Mint specifies the following (in the corresponding UI dialog):

  • Instrument: The identifier of the instrument that will be minted.

  • Amount: The amount that will be minted.

  • Registrar: The ledger party of the Registrar of the token that will receive the Mint request and needs to accept (or reject) it.

  • Reference: A reference field to provide context, such as the reason for the mint or the agreement under which the tokens are being minted.

• Mint Acceptance/Rejection:

  Only the Registrar is authorized to accept or reject Mint requests. Upon accepting, the creation of tokens is executed for the requesting party, provided they have the necessary credentials. Upon rejection, the registrar may provide a reason for the rejection, and the mint offer is voided.

• Mint Cancellation:

  The party that requested the mint has the ability to cancel it before acceptance by the Registrar.

Attention

The mint workflow currently relies on the Operator backend to execute accepted mint requests. This step is deprecated and will be disabled in a future release in favour of a 2-step process between the requesting party and the registrar.

Burn

The registry’s Burn request workflow allows authorized parties to remove tokens (Holdings) of a specific instrument. This process uses a request-accept-execute workflow to ensure that only eligible parties can initiate and approve the burning of tokens.

• Prerequisites/Credential Checks:

  • Burning requires that the tokens to be burned have already been minted, see last section, and are held by the requesting party.

  • It is validated that the requestor has valid Instrument Issuer credentials for the instrument as defined in the InstrumentConfiguration, ensuring that only authorized parties can burn Holdings. If no Instrument Issuer credentials are specified in the InstrumentConfiguration, any party is eligible to request a burn.

• Burn Request:

  The party requesting the Burn specifies the following (in the corresponding UI dialog):

  • Instrument: The identifier of the instrument that will be burned.

  • Amount: The amount that will be burned.

  • Registrar: The ledger party of the Registrar of the token that will receive the Burn request and needs to accept (or reject) it.

  • Reference: A reference field to provide context, such as the reason for the burn or the agreement under which the tokens are being burned.

• Burn Acceptance/Rejection:

  Only the Registrar is authorized to accept or reject Burn requests. Upon accepting, the permanent removal of tokens is executed for the requesting party, provided they have the necessary credentials and hold sufficient tokens. Upon rejection, the registrar may provide a reason for the rejection, the burn offer is voided, and locked Holdings are released.

• Burn Cancellation:

  The party that requested the burn has the ability to cancel it before acceptance by the Registrar. Upon cancellation, any locked Holdings are released and can be used for other purposes.

Attention

The burn workflow currently relies on the Operator backend to execute accepted burn requests. This step is deprecated and will be disabled in a future release in favour of a 2-step process between the requesting party and the registrar.

Transfer

The registry’s Transfer workflow, which is an Transfer Instruction API implementation of the Canton Network Token Standard, allows authorized parties to move tokens (Holdings) of a specific instrument from one party to another at a registrar. This process uses a offer/accept workflow to ensure that only eligible parties can initiate and approve the transfer of tokens.

• Prerequisites/Credential Checks:

  • To initiate a transfer, the sending party must already possess the tokens to be transferred, see the Mint workflow above for creating tokens.

  • The Registrar must have created a TransferRule contract isntance.

  • Upon offering and accepting a transfer, it is verified that the sender has valid Instrument Holder credentials for the instrument as defined in the InstrumentConfiguration. Similarly, it is checked upon accepting the transfer that the receiver has valid Instrument Holder credentials. This ensures that only authorized parties can transfer Holdings. If no Instrument Holder credentials are specified in the InstrumentConfiguration, any party is eligible transfer to any other party.

• Transfer Offer:

  The party initiating the transfer (the sender) specifies the following (in the corresponding UI dialog):

  • Receiver: The ledger party of the receiver.

  • Instrument: The identifier of the instrument to be transferred.

  • Amount: The number of tokens (Holdings) to transfer.

  • Registrar: The ledger party of the Registrar overseeing the transfer.

  • Reference: A field to provide context, such as the reason for the transfer or for tracking purposes.

  Note

  Before the command is submitted by the UI:

  1. Holdings are automatically selected to cover the transfer amount.

  2. An API call is being made (in the background) to the corresponding Utilities’ token standard endpoint to retrieve required additional choice context (including disclosure). This includes the InstrumentConfiguration, the required Credentials, and other required input.

  As a result of executing the command, the specified amount of a Holding gets locked for the transfer, which is visually indicated by a lock symbol on the Holding page in the UI.

• Transfer Acceptance/Rejection:

  The receiver has the ability to either accept or reject the transfer offer. Upon acceptance, the ownership of the tokens is changed from the sender to the receiver within the registry. Thereby the registrar is not changed. Upon rejection, the transfer offer is voided, and any locked Holdings are released back to the sender.

  Note

  Before submitting the accept/reject command, an API call is being made (in the background) to the corresponding Utilities’ token standard endpoint to retrieve required choice context (including disclosure). For the accept endpoint, this includes the TransferRule, the InstrumentConfiguration, the required Credentials, and other required input. For the reject endpoint, the context is currently empty.

• Transfer Withdrawal: The sender has the ability to withdraw (i.e., cancel) the transfer before acceptance by the receiver. Upon withdrawal, any locked Holdings are released and can be used for other purposes.

  Note

  Before submitting the withdraw command, an API call is being made (in the background) to the corresponding Utilities’ token standard endpoint to retrieve required choice context (including disclosure). Currently this context is empty.

By using the request/accept workflow, the registrar guarantees that all transfers are securely managed and authorized, preventing unauthorized or erroneous transactions. This approach helps maintain the integrity and traceability of token ownership within the registry.