tbDEX Wallet in 5️⃣ minutes

Overview

The role of a Wallet App in a tbDEX ecosystem is to find liquidity for its customers. Let’s build a tbDEX-enabled wallet in under 5 minutes. You will learn how to:

✅ Integrate the tbDEX SDK into a wallet app

✅ Connect a wallet app with a PFI (Participating Financial Institution)

✅ Use a wallet app to send tbDEX messages to a PFI to facilitate a transaction

Let’s go!

Wallet App Basics

In this exercise, your app is responsible for helping your customer, Alice, exchange USD for KES. First, we'll create a DID (Decentralized Identifier) for Alice.

Create Customer's DID

In order for you to communicate with PFIs on your customers' behalf, they will need a DID. Let's create a DID for Alice now:

See Alice's DID

Connect to a PFI

To connect to a PFI, all you need is their DID. Let's use the DID of a mock PFI:

Get Offerings

All PFIs have Offerings which are a menu of services they provide. Offerings describe the currency pairs and transaction parameters offered. Let's fetch all of the offerings from the PFI:

See the PFI's Offerings

Once you have all of the PFI's offerings, you can filter it based on a variety of factors, including the currency pair you're looking for. In this case, you're looking for an offering that exchanges USD for KES:

Obtain Verifiable Credentials

The Offering we selected has a requiredClaims section that specifies Verifiable Credentials (VCs) Alice needs in order to be eligible for the Offering. This PFI requires Alice to have a credential whose credentialSchema matches the schema of the KnownCustomerCredential, as outlined in the requiredClaims section of the Offering. Additionally, that credential must be issued by a specific issuer as described by the issuer's DID below:

{"requiredClaims": {
          "id": "3f78edc1-9f75-478b-a0d8-c9ee2550d366",
          "format": {
            "jwt_vc": {
              "alg": [
                "ES256K",
                "EdDSA"
              ]
            }
          },
          "input_descriptors": [
            {
              "id": "73b86039-d07e-4f9a-9f3d-a8f7a8ec1635",
              "constraints": {
                "fields": [
                  {
                    "path": [
                      "$.vc.credentialSchema.id",
                      "$.credentialSchema.id"
                    ],
                    "filter": {
                      "type": "string",
                      "const": "https://vc.schemas.host/kcc.schema.json"
                    }
                  },
                  {
                    "path": [
                      "$.vc.issuer",
                      "$.issuer"
                    ],
                    "filter": {
                      "type": "string",
                      "const": "did:dht:bh8me68fsdb6xuyy3dsh4aanczexga3k3m7fk4ie6hj5jy6inq5y"
                    }
                  }
                ]
              }
            }
          ]
        }
      },

As a result, we'll help Alice apply for the SanctionsCredential she needs to satisfy the PFI's requirements:

Apply for an example Known Customer Credential

VCs are stored as JSON Web Tokens (JWTs). Your wallet app has saved Alice's new VC into an array named customerCredentials. Let's now select Alice’s credential to meet the PFI's requirements:

Request Quote

Now that you've found an offering that matches Alice's request, your app can request a quote from the PFI to obtain a formal offer based on Alice's preferred payment methods.

See the RFQ

After creating an RFQ message, you can verify that it is properly constructed and its data satisfies the Offering's requirements.

If no exceptions are thrown, you'll sign the RFQ with Alice's DID to ensure its authenticity.

Then finally, you'll send the RFQ to the PFI to initiate the transaction.

Submit RFQ

Process Quote

In response to your RFQ, the PFI will write a Quote message to the exchange if they are able to fulfill Alice's request, or a Close message if not. Here's how to obtain that message:

View Quote

Place Order

The Quote contains the exact exchange rate including any fees. Your app can present this to Alice to determine if she wants to proceed with the transaction. If she does, you'll create an Order message:

Create Alice's Order

Once you have an order message, you can sign it with Alice's DID and send it to the PFI to execute the transaction.

Submit Order to PFI

End Transaction

To end the transaction, the PFI will write a Close message indicating whether the transaction successfully completed or not. They'll also include a reason for closing the transaction which will contain more information that you may find helpful in event of a failure.

View your close reason

Next Steps with tbDEX

Congratulations on creating your first Wallet! In just a few minutes you were able to contact a PFI for its offerings, request a quote, and place an order for Alice to swap USD for KES.

If you’d like to get started building an even more robust wallet, you can see our full Wallet guide. Additionally, you can learn more about building your own PFI, as well as becoming a Credential Issuer on the tbDEX network too!