Denominations

Overview/Getting Started

1. Call the PATCH enterprise endpoint to specify a banker-account-id
2. Create a new file that will act as your currency, eg. TDN.
3. Create files for each denomination you wish to use. These files must use the currency file ID from step 2 as the file-type and specify an integer denomination in the payload.
4. Now generate actual notes and give them to your banker. eg. Bulk create a few files of each of the file-types specified in 3.
5. Give your actual accounts some notes by following the same instructions in step 4.
6. Now you're ready to create denominated transactions! Just create a new transaction with a value attribute and specify the currency file ID from step 2 in relationships/file-type/data/id

2. Designating a Banker Account

For v1 of denominations, the process of making change goes through an account that you designate as the banker account. This is set via the banker-account-id property on the enterprise you wish to transact under. You can set the banker account through the API using the normal update enterprise call. The banker account must be within the enterprise.

        PATCH /enterprises/enterprise-id

        {
            "data": {
             "attributes": {
           "banker-account-id": "75316021-bf45-4a0f-a14c-78abd8c56fe1"
               }
            }
        }
        

3. Creating Denominated Files

You may now create a new file with an integer denomination attribute as a part of its payload. Any files ("notes") you create of that file-type are now considered to have that denomination's value. If a file's type does not have a denomination it is not considered to have any value and will not be used.

Denominated files hierarchy example

        TDN File

        -> 1 TDN bill file (file-type: TDN File, payload denomination: 1)
        --> Individual 1TDN bill (file-type: 1 TDN bill file)

        -> 5 TDN bill file (file-type: TDN File, payload denomination: 5)
        --> Individual 5TDN bill (file-type: 5 TDN bill file)
        

Creating a new "5 note" file type

eg: Any files that use this file ID as a file-type will be considered to be worth 5 notes. You probably want to create this file type for an account that is not likely to trade them away.

        {
            "data": {
             "type":"file",
             "attributes":{
               "payload":{
                                "description": "The 5-currency note file type"
                 "denomination": 5
               }
             },
             "relationships":{
               "initial-account":{
                 "data":{
                   "type":"account",
                   "id":"499c8a81-0b6b-40ed-87f6-7c201813ea1d"
                 }
               },
                "file-type":{
                 "data":{
                   "id":"Currency file type, eg. TDN file-id"
                 }
               }
             }
            }
        }
        

Creating a single instance of a "5 note"

eg. In order to create an actual 5 note bill, create a new file with the above file's ID as the file-type:

        {
            "data": {
             "type":"file",
             "attributes":{
               "payload":{
                                "description": "A single instance of a 5-note TDN bill"
               }
             },
             "relationships":{
               "initial-account":{
                 "data":{
                   "type":"account",
                   "id":"499c8a81-0b6b-40ed-87f6-7c201813ea1d"
                 }
               },
                "file-type":{
                 "data":{
                   "id":"5-currency note file type, eg. 5 TDN file id created above"
                 }
               }
             }
            }
        }
        

4. Transacting Denominated Files

When creating a txn you may now specify a value attribute. If specified, the HLT creates a "workflow" txn that is identical to a normal txn, except with a transaction-ids property that contains an ordered list of all txns in this workflow. TaaS will create an entity for both the workflow and its child txns but it returns the workflow txn with a status of "processing". Both the HLT and TaaS listen for txn updates and keep the workflow and its child txns up to date. Note that when performing a denominated transaction, there will always be both a workflow transaction and a child transaction, even if you have sufficient change.

Creating a denominated transaction

eg. Note that the file type ID specified in this transaction determines the TYPE of notes to use in the transaction. If you want to transact any bills of type TDN, you should specify the TDN file ID as the file-type.

Request

        {
            "data": {
             "attributes":{
               "value": 37
             },
             "relationships":{
               "sender":{
                 "data": {
                   "type":"account",
                   "id":"4683dda9-9a4a-42c8-965e-7b48c4f23930"
                 }
               },
               "recipient":{
                 "data": {
                   "type":"account",
                   "id":"f06b3363-3030-43fe-943f-0349d55d1675"
                 }
               },
               "file-type":{
                 "data": {
                        "id":"Currency ID, eg. TDN file-id"
                                }
               }
             }
            }
        }
        

Response

Note that since the request was for a denominated transaction, the response displays the workflow or parent transaction with a settlement status of processing. There is also a transaction-ids property that displays an ordered list of the transactions that are a part of this workflow.

The expected incoming and outgoing files fields refer to the files the workflow expects to receive back from the banker and send on to the final recipient. This can be used to calculate the expected balance when this workflow has completed.

        {
         "data" [{
           "type": "transaction",
           "id": "86965fef-c8bb-4603-a6fe-768b90f7ed2d",
           "attributes": {
               "metadata-hash": nil,
               "workflow-id": "86965fef-c8bb-4603-a6fe-768b90f7ed2d",
               "transaction-ids": ["e92b862f-2fbb-4cef-913f-d1cc8f44f57a"],
               "value": 37,
               "quantity": 0,
               "status": "pending",
               "settlement": "processing",
               "transaction-type":"denominated",
               "initiated-ts": 1563476764678,
               "enterprise-id": "b840c14e-e38b-4137-991b-533e90156262",
               "expected-incoming-file-types": {
                 "5647d02c466c6629211daf9e4c29c99c59c7d8fc3abd2e60f7e5f44729f72922": 1
               },
               "expected-outgoing-file-types": {
                 "c28f927dc64960f03b2b70b0a97475e5f07b6ef2e711bdea2484376b8af63519": 2
               }
           },
           "relationships": {
           ...
        }
        

For "denominated" txns, the HLT first attempts to find the minimum number of available files of the specified file-type-id whose denomination values sum to the desired txn value. If enough files are found, a txn is created for those file IDs and the txn ID is added to the workflow. If there aren't enough files, the HLT attempts to find the smallest larger note that can be used to make change. If such a note is found, a :request-change txn is created instead for that file between the sender and the enterprise's designated banker account, if one exists.

If there are no larger files available to change or no banker is specified on the enterprise, an insufficient-files error will be returned.

Once the :request-change txn has completed, both the HLT and TaaS receive a message from SNS. TaaS updates the txn entity while the HLT determines the next steps. If the txn is successful, the HLT looks at the banker's files and determine the fewest files that can sum to both the original value and also the provided denomination. If found, a new :make-change txn is created between the banker and the sender with the file IDs for the change.

If there aren't enough files, an :insufficient-change txn is created returning the exact denomination file to the sender. Once that txn completes the workflow entity will be updated with the "insufficient-files" status.

When the :make-change txn completes, the HLT will again attempt to find the minimum files for the requested value. If those files are found, a final :transact txn is created between the sender and the recipient for those files. Finally, the workflow transaction is updated with a status of "recipient-complete".

If no files are found here a workflow-error event is published to SNS that marks the workflow as failed with status "tx-error" and the relevant error message.

The only change to TaaS is that a workflow txn is returned instead of a single child txn when specifying a value. Updates to both the workflow and its child txns will still be published to SNS, although the workflow txn will only display the following statuses: ["processing" "recipient-complete" "insufficient-change" "tx-validation-error"] or the error code of the child transaction. For more detail you will need to look at the workflow txn's transaction-ids and inspect their details.