Developer's Guide: Digital DLT-FIAT Wallet

Welcome to the developers guide for the PISTIS Digital DLT-FIAT Wallet component.

Introduction

A component responsible for overseeing the platform’s value transactions in a DLT private network, guaranteeing quick and reliable exchanges. It also serves as a crucial interface with traditional FIAT banking accounts, enabling seamless fund transfers and effortless conversion between fiat and digital tokens.

Technologies

The Digital DLT-FIAT Wallet component is a Rust web-based application that offers a RESTful API capable to provide support for both the FIAT and the DLT ecosystem with all the needed functionalities such as authentication and authorization. It is combined with a minimal Postgres 16 database to store various important information.

Access

Three distinct instances of the application are available:

  1. https://pistis-market.eu/srv/payments
  2. https://develop.pistis-market.eu/srv/payments
  3. https://sph.pistis-market.eu/srv/payments

Usage

All API calls require an authorization bearer token issued by the PISTIS Keycloak component.

Details of all supported functionalities, along with their corresponding API endpoint specifications, are provided in the component Swagger.

Curl access example:

curl --location 'https://pistis-market.eu/srv/payments/v0/dlt/health_checker' \
--header 'Authorization: Bearer *****'

Payments

Additionally, a payments PISTIS repository related with Digital DLT-FIAT Wallet component exists.

This repo contains demonstration scripts on how a component can interact with ICCS DLT-FIAT wallet through the REST API that the component provides. The following listing presents the dirpath of this repo:

* scripts
    contains sample bash code demonstrating how a user can use dlt-fiat wallet restAPI backend

    /
    +-- scripts
        |--pistis.common
        |   a set of common functions for interacting with dlt and fiat restAPI and various log
        |   routines used in the scenario scripts
        +-- scenarios
            +-- logs/
            |   |   This particular folder and its files living here are all included
            |   |   in the /.gitignore. on every scenario invocation, a link file ```latest```
            |   |   will point to the log of the running script
            |   |
            |   |-- basic.scenario.`date +%Y%m%d_%H%M%S`,   example basic.scenario.20240414_121922
            |   |-- backup_restore.scenario
            |   |-- [ latest ]
            |-- basic.scenario
            |       a very basic scenario with 3 wallets, one for owner and 2 for factories.
            |       Scenario performs:
            |           two cash-in operation for both users
            |           one transaction between user1 and user2, user1 buys a dataset from user2
            |           two cash-outs for both users. User1 cash out all its dlt tokens
            |-- backup_restore.scenario
            |       scenario that demonstrate the backup-restore procedure
            |       backup files filetype is .stronghold and are saved in The
            |       configuration file of the ```pistis_api``` component binary
            |-- cash-out.scenario
            |       move all tokens from users to owner
            |-- nft_payments.scenario
            |       variation of basic.scenario where user1 creates an nft and then user2
            |       purchase with NFT payment user1 dataset
            |-- mint_nfts.scenario
            |       Mint nfts for 3 users, 2 for owner, 3 for user1, 4 for user2.
            |-- burn_nfts.scenario
            |       Burns all the NFTs of the users except their first one

For a user to execute a script, they must navigate to the 'scenarios' directory. Below is an example of how to run the basic.scenario script:

cd scripts/scenarios/
#config that pistis_api is operational
./basic.scenario

The code snippet above will try to:

  1. Wallet Creation: Initializes three wallets
    1. One acts as the platform owner, named Pistis_Owner_Wallet
    2. Two serve as user factories, named OASA and AIA.
  2. Token Request: The Pistis_Owner_Wallet requests tokens from the network faucet on the public IOTA testnet (alpha version).
  3. Dataspace Transactions: Demonstrates a sample dataspace purchasing along with user factory wallet cash-in and cash-out functionalities. During the dataset purchase tokens will be transferred both to the platform owner (as platform fees) and the data seller.

Snippet will also produces log files within the logs/ directory. These logs provide detailed of how curl was invoked by the script in order to interact with DLT-FIAT component through the terminal.

Another example of how to use backup restore logic of a wallet:

cd scripts/scenarios/
#config that pistis_api is operational
./backup_restore.scanario

The script backup_restore.scenario will create 2 wallets. The first one acts as the platform owner, so it will request tokens from DLT faucet. Then, it will create wallet backup files in the current working directory. All backup files will be moved to the /tmp/ directory. Finally, using the corresponding files, it will restore and recreate the wallets under /tmp.

Every scenario needs to call function scenario_init at start and scenario_finish that perform all the preparation and closure tasks, like verifying the connectivity to the PISTIS_DLT_FIAT binary. Although the binary uses port 3000 for its incoming connections, users can modify this by updating the relevant PISTIS_DLT_FIAT config entry. As a result, the scenarios may lose communication with the server in case of a changed port. Users are able to define were PISTIS_DLT_FIAT listens by setting the environmental variable PISTIS_API_URL. For example, assuming that PISTIS_DLT_FIAT is listen on port 5678 on localhost then user need to call the scenario like this:

cd scripts/scenarios/
#config that pistis_api is operational
PISTIS_API_URL=localhost:5678 ./backup_restore.scenario

Under directory scripts/scenarios/examples you can see a list of curl commands that implement the various scenarios