Approval with API

When configured for API mode for approvals, the Virtual Signer will call your own API to let it decide when to approve, reject, or abstain from voting on or signing requests.

When ApprovalMode is set to "API" in configuration, the Virtual Signer will call the URLs defined in ExternalTransactionApprovalURL and ExternalReshareApprovalURL for the approval of requests. The Virtual Signer request and the API response must implement the HTTP Message Signatures protocol, based on IETF HTTP Message Signatures and as outlined below.

The response signatures guarantee that indeed the original customer server generated the responses.

Preparing for Setup

As a customer, use a secure server to create an EdDSA key pair with openssl, and be sure to save these files safely and on a secure device.

openssl genpkey -algorithm ed25519 -out private_ed.pem
openssl pkey -in private_ed.pem -pubout -out public_ed.pem

Before running a Virtual Signer instance, set ApprovalHTTPPublicKeyHex in configuration to be the value of the public key has a hexadecimal encoding of the PEM format (public_ed.pem). For example, for this public key in PEM format:

-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAyS9WQDUN9LeyDc1nV6wyKgGPyngsHYNmdQaj6U2suuk=
-----END PUBLIC KEY-----

set in configuration its ASCII string value (including new lines) encoded in hexadecimal:

"ApprovalHTTPPublicKeyHex": "2d2d2d2d2d424547494e205055424c4943204b45592d2d2d2d2d0a4d436f77425159444b32567741794541795339575144554e394c65794463316e563677794b674750796e677348594e6d6451616a3655327375756b3d0a2d2d2d2d2d454e44205055424c4943204b45592d2d2d2d2d",

📘
To convert the PEM file to hex easily, you may use an online tool like the one here. This is a non sensitive file containing a public key.
Keep in mind that you should only ever put the public part of a keypair (public_ed.pem in this case), marked with the words "BEGIN PUBLIC KEY" into an online form.
The private part of your keypair should be moved immediately into secure storage (like a secrets manager or HSM) and not exposed to your OS clipboard or the internet in any way.

The service that implements the customer API will receive requests from the Virtual Signer with the Accept-Signature and VS-Nonce headers. Accept-Signature will have keyid set to eddsa-key and will contain the signature fields content-type and digest. The service must use the EdDSA private key (private_ed.pem) to sign its response and set signature in the header.

Your approval API should then call out to the io.finnet GraphQL endpoint (docs) at the endpoint https://api.iofinnet.com/v0/graphql to get the information about the request that it needs to run your policies.

Once the customer API responds to the inbound HTTP request, the Virtual Signer (VS) will validate the response signature. If the validation fails, the Virtual Signer will encounter an error and will retry after a short delay.

The Virtual Signer includes a VS-Nonce header in its request. It is a random positive integer less than or equal
to JavaScript's Number.MAX_SAFE_INTEGER. Be sure to use a cryptographically secure random number generator (CSPRNG) to produce this value.
The response must echo back the token in its JSON, as shown above.

Note that even though in section 6.2.2 of the spec the algorithm name is ed25519 the Virtual Signer expects the
algorithm key in signature to be set to hs2019.

The Request from the VS

The Virtual Signer sends requests serialized as JSON to the customer's API. That is, the body of the request in its
entirety is the JSON serialization of two vault objects, depending on the type of user action: ReshareRequest or
TransactionRequest. See ReshareRequest and TransactionRequest for the details of these objects.

A ReshareRequest represents a vault creation or a request to reshare, that is, to change the party composition
and/or weights of the vault. On the other hand, a TransactionRequest represents a request to sign either a transaction (as in a transfer, a mint, a burn, etc) or a sign operation (as in a signature of data in a standard format).

Example Request

POST https://<customer_service>/my-api/transaction-approval

Headers: 
"Accept-Signature": "sig1=(\"content-type\" \"digest\");nonce=83727271837;keyid=\"eddsa-key\""
"VS-Nonce": 83727271837

Body: {"__typename":"TransactionRequest", "id": "..." ...

The Response from your API

The request and the response follow the HTTP Message Signatures protocol. The sample scripts have an Ed25519 private key. They take a JSON that is the body of the response to produce a content digest and a signature. This is a sample response body:

{ "status": "rejected", "nonce": 3827271 }

Possible values of status in your API response are approved, rejected, or abstain which will affect the voting performed by the Virtual Signer accordingly.

The response JSON must echo back the nonce originally included in the request (VS-Nonce header). Its maximum value is 0x7FFFFFFFFFFFFFFE.

Example Response

Headers:  
"Content-Type": "application/json",
  "digest": "SHA-512=OA3Yt3rU5+UHDI06FhRqZQtiKbwuytApQ+sVIS8hQ1p29i0q0yX4JXv2lhPwpZGVmv66X0ZkMBRimTq1EIiP3g==",
    "Signature": "keyId=\"eddsa-key\",algorithm=\"hs2019\",headers=\"content-type digest\",signature=\"zlJViX2CyB49266bswzk2zMbCc38y8N3iI1dXEoPJt95v2icTgZoFmI9cvtGFcRyycFfd3E/TUeuiGVs/eLfAQ==\"",

Body: `{ "status": "approved", "nonce": 83727271837 } `

Full Example

Here is a more detailed sample request/response pair, where the Python script within the Azure Container App
produces the signed response, following the HTTP Message Signatures protocol:

 % curl -v --location 'https://vsapprovaltestfunc.greenbay-b1c1bd0a.eastus.azurecontainerapps.io/api/httpvsapproval' \
--header 'Accept-Signature: sig1=("content-type" "digest");nonce=83727271;keyid="eddsa-key"' \
--header 'VS-Nonce: 83727271' \
--header 'Content-Type: application/json' \
--data-raw '{
    "__typename": "TransactionRequest",
    "amountOriginal": "0.00606103",
    "amountUsd": "2.78440028823084577",
}'
*   Trying 4.157.75.188:443...
* Connected to vsapprovaltestfunc.greenbay-b1c1bd0a.eastus.azurecontainerapps.io (4.157.75.188) port 443 (#0)
[...]
> POST /api/httpvsapproval HTTP/2
> Host: vsapprovaltestfunc.greenbay-b1c1bd0a.eastus.azurecontainerapps.io
> User-Agent: curl/8.1.2
> Accept: */*
> Accept-Signature: sig1=("content-type" "digest");nonce=83727271;keyid="eddsa-key"
> VS-Nonce: 83727271
> Content-Type: application/json
> Content-Length: 439
> 
* We are completely uploaded and fine
< HTTP/2 200 
< content-type: application/json
< date: Fri, 04 Aug 2023 21:30:53 GMT
< server: Kestrel
< request-context: appId=cid-v1:62fa0dbc-ae2b-4a3d-b3d4-593648a55c62
< signature: keyId="eddsa-key",algorithm="hs2019",headers="content-type digest",signature="Ow0Sh6VItuKtC6nqAeB7Qx5GPcVe3rvjbZeRlLoRbYZKLawOv3ruFdoiAWWiKdgyxwITDpmFO8TqSfvO9140BQ=="
< digest: SHA-512=b9e4zA1CER+mr+K+Pmn1G1OaFc1cWXY5lKtk6Mdh3fmyy0mwLVFKmdpNidd3apveLmiRXFSAywg9YzMHMJUN3g==
< 
* Connection #0 to host vsapprovaltestfunc.greenbay-b1c1bd0a.eastus.azurecontainerapps.io left intact
{"status": "approved", "nonce": 83727271}

Setting up your API

The data that you get from the Virtual Signer sent to your own API looks like:

{
  "__typename": "TransactionRequest",
  "id": "o2gvirlhkrgmxylma8ho7dgr",
  "organisationId": "clpbbig0n000208jp48n82m3j",
  "expiresAt": "2024-06-13T22:51:20.195Z",
  "transactionRequestStatus": "PENDING"
}

Your approval API should call out to the io.finnet GraphQL endpoint at the endpoint https://api.iofinnet.com/graphql using the id to get the information about the request that you need to run your policies.

Sample API Implementations

You may find some public sample scripts here: Approval Integration with the Virtual Signer on GitHub. There are samples for:

AWS Lambda
Azure Container App with Python (Readme)

There are two sample scripts that produce signed approval/rejection responses. A NodeJS lambda intended to run on AWS, and a Azure Container App with a Python script. The former can be found in the doc/approval_API_samples/lambda folder and the latter in doc/approval_API_samples/azure_container_app_proj. azure_container_app_proj is a Visual Studio Code project. See the Readme for more information, including deployment instructions.

In the samples, the lambda folder contains a sample NodeJS script for use as a AWS lambda. The azure_container_app_proj folder contains a sample Azure Container App with a Python Function that can support the development of an API for approvals. This project will deploy the Python script within a Docker image.

📘
Note
Note that both NodeJS and Python scripts refer to cryptographic libraries. It is common for cryptographic libraries to contain native bindings that are CPU-specific. By deploying these projects as Docker containers, you will avoid cross-platform incompatibilities.
The Azure Container App above contains a Dockerfile for deployment with Docker.

Preparing for Setup

📘

The Request from the VS

Example Request

The Response from your API

Example Response

Full Example

Setting up your API

Sample API Implementations

📘Note

📘
Note