Approving A Transaction Request

Basic Description

This endpoint is used to approve a Transaction Request in Taurus-PROTECT. It is important to note that Taurus-PROTECT allows a user to sign multiple Transaction Requests within a single interaction with the API.
To understand the process of signing as well as what is a Transaction, what is a Request and the differences between these two concepts, please refer to the following page in the Taurus User Guides.

This endpoint would accept a POST Request with a JSON payload, including the generated ECDSA Signature of the array of all the hashes within the metadata of each Transaction Request that needs to be signed.

Prerequisites

Required Roles

Certain API endpoints require that the user has a specific role in order to access them. Roles are used to restrict access to certain functionality within the system and ensure that only authorized users are able to perform specific actions.

Here is the list of required Roles for this particular endpoint:

• RequestApprover
• TPUser

To find out more about roles, please refer to the following page in the Taurus User Guides.

Required Input Parameters

Certain API endpoints require specific input parameters. Here is the list of Required Input Parameters for this particular endpoint:

• signature: the computed ECDSA signature for one or more Transaction Requests, encoded in Base64.
• requestIds: one or more Transaction Request IDs to be approved.

📘

Preconditions

It is important to note the correct ECDSA Signature needs to have been properly generated and the relevant Transaction Request(s) need to pre-exist on the system for the approval process to go through successfully.

🚧

ECDSA Signature

An ECDSA signature allows a user to publish a public key and then create a signature of some data with their private key, such that anyone can verify that the signature was created by the owner of this public key. To find out more about the computation and encoding of the appropriate ECDSA signature, please refer to the following page.

Signature Example

You can find a basic example in Bash on how to generate an ECDSA Signature.

export METADATAHASH='fda859afd5dcc16f7abec8e7ab7fc528d90b094e43eeb111037581c45f8e16b5'

output=$(echo -n '["$METADATAHASH"]' | openssl  dgst -sha256 -sign [email protected] | openssl asn1parse -inform DER )
# output = 0:d=0  hl=2 l=  70 cons: SEQUENCE          
#     2:d=1  hl=2 l=  33 prim: INTEGER           :9F51A2A2049DBF22F281478337F6D6EA4D7987C40A2F256DF0965164D0D640FB
#    37:d=1  hl=2 l=  33 prim: INTEGER           :FA037EA62EE530F558A79025AF006C46E087AFAB30F9CE61D43AF3C3C0505A67

num1=$(echo "$output" | cut -d: -f3 | cut -c0-64 ) # 9F51A2A2049DBF22F281478337F6D6EA4D7987C40A2F256DF0965164D0D640FB
num2=$(echo "$output" | cut -d: -f4 | cut -c1-65) # FA037EA62EE530F558A79025AF006C46E087AFAB30F9CE61D43AF3C3C0505A6

# concatenate the 2 outputs above
newoutput="$num1$num2" #9F51A2A2049DBF22F281478337F6D6EA4D7987C40A2F256DF0965164D0D640FBFA037EA62EE530F558A79025AF006C46E087AFAB30F9CE61D43AF3C3C0505A67

echo -n "$newoutput" | xxd -p -r | base64 | tr -d '\n' 

# ECDSA Signature: Sn1GiogSdvyLygUeDN/bW6k15h8QKLyVt8JZRZNDWQPv6A36mLuUw9VinkCWvAGxG4IevqzD5zmHUOvPDwFBaZw==

👍

Signature Result

A successful final output of the above script might look like this:

Sn1GiogSdvyLygUeDN/bW6k15h8QKLyVt8JZRZNDWQPv6A36mLuUw9VinkCWvAGxG4IevqzD5zmHUOvPDwFBaZw==

This result is what you eventually need to add within the JSON Body of the below Request.

Call Example

You can find a basic example in cURL below.
Please note that you will need to update the BASEURL and the APITOKEN for the command to function.
In this example, we use the computed ECDSA signature, encoded in Base64, to sign the Request with ID 443.

export BASEURL=https://taurus-protect-instance.com
export APIToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwiZXh0ZXJuYWxVc2VySUQiOiJ0ZWFtMUV4dGVybmFsVXNlcklEIiwidGVuYW50SUQiOjEsImNhcGl0YWxUZW5hbnRJRCI6MSwiZmlyc3RuYW1lIjoiSm9obiIsImxhc3RuYW1lIjoiRG9lIiwicm9sZXMiOlsidHB1c2VyIl0sImVtYWlsIjoidGVhbTFAYmFuay5jb20iLCJ1c2VybmFtZSI6InRlYW0xIiwiand0X3JlbmV3YWJsZV9hbW91bnQiOjAsImlzX3RvdHBfZW5hYmxlZCI6ZmFsc2UsImF1dGhfc3RhdHVzIjoiU1VDQ0VTUyIsImxhc3RfbG9naW4iOiIyMDIzLTAxLTAxVDAwOjAwOjAwLjE0OTc0NDIzMloiLCJsb2dnZWRfaW5fd2l0aF9zc28iOmZhbHNlLCJrZXkiOiIiLCJleHAiOjE2ODEyMTkyNzYsImlhdCI6MTY4MTIxNzQ3Nn0.K_85arIrigpkN1yHttCydpeT6oVg2c6PyQnuji907Og

curl --location "$BASEURL/api/rest/v1/requests/approve" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $APIToken" \
--data '{ 
  "signature": "I0xWyXI3L33DMZAKvvKXnlWD3GGXWh0AuL5zHD12DGp2/pR2h2MbgiQZrNGB27s/iB938UgMK1xUhbm1fNx8nw==",
  "comment": "API-Documentation - Test 12", 
  "requestIds": [ "112" ]
}'

This piece of code sends a POST request to https://your-protect-instance.example.comapi/rest/v1/requests/approve with the JSON string in the request body including the relevant ECDSA signature, encoded in Base64, and the list of Request IDs.

👍

Call Result

A successful response for the POST call to approve a Request might look like this:

{
    "signedRequests": "1",
    "signatures": "1"
}

Taurus-PROTECT responds with a JSON object containing the number of approved Transaction Request details.

Requirements for Future Use

For this particular endpoint, we need to store the Request id to be able to check the status of the Request in the next steps, during the process of HSM approval and the transaction broadcasting to the respective blockchain.

You can find the Swagger-generated page for this endpoint in the following link.