Hyperledger Aries ACA-Py Agents Setup and Running Tutorials — Part IV — One-Time Agent-level Connection Channel Establishment

Introduction

In Part I, I’ve introduced the general benefits of using SSI and why Hyperledger Indy and Aries can fit in the big picture. In Part II, a scenario overview and tools were described. Part III shows details on how to set up a Dev environment to run an ACA-Py agent V0.6.0. In this Part IV, it will focus on the one-time agent level connection channel establishment.

Why One-Time Agent-Level Connection Channel Establishment

After running a local ACA-Py agent, it won’t be able to communicate with other ACA-Py agents by default, as there is no connection channel being established between them. This connection channel establishment becomes a prerequisites to enable ACA-Py agents to communicate as stated in Layer 2 in ToIP stack (see figure 1). ACA-Py implements the DIDComm P2P protocol to enable one ACA-Py agent to talk to other ACA-Py agents by setting up the underlying one-time connection channel for all further communication.

figure 1 — Layer 2 in ToIP

How to do it in practice

Please follow all the steps in Part III to make sure you have set up two ACA-Py agents (one runs as an issuer, and the other runs as a holder), and each runs on a separate Azure VM. Once the two agents run properly, you can access ACA-Py’s built-in Open APIs by accessing the URL: {issuer agent VM’s public IP}:{Self-defined Port II} (see instructions in Part III). In the list of all APIs, find the a POST API named: /connections/create-invitation (see figure 2). Click on the button “Try it out”, you will see a built-in JSON body that have key/value pairs (see figure 3). Delete all of them and only keep the pair of the curly braces (see figure 4).

figure 2 — API for creating an invitation from one agent that will initialise the connection channel establishment with other agents

figure 3 — Default Key/Value pairs in the JSON Body

figure 4 — Delete all the contents in JSON body

If you do plan to retry this process many times like what I do, I would then recommend you to use a tool like Postman (see figure 5), and create and save your APIs there, so you can avoid repeating these steps in the Open API. This is the main approach I use, so in the rest of the tutorials, I only show all other APIs in the Postman.

Note: I’ve changed my VM’s real IP and Port to parameters for privacy purposes in figure 5, but you do need a real VM’s IP and Port in Postman to make the API call happen. For the rest of the tutorials in this Part IV and all future Parts, if you see VM’s IP and Port in the screenshots, please change them to your own real IP and Port number.

figure 5 —call an API on the issuer agent to send out an invitation to the holder agent

Either click on the “Execute” button in the Open API or a “Send” button in the Postman, you will a response message as shown in figure 6.

figure 6 — API response

Please copy the entire value of the “invitation” key including the start and end curly braces as highlighted in figure 7 without making any changes.

figure 7 — Copy and paste the value of the “invitation” key

Making sure your holder ACA-Py agent is also up and running. Put a new POST API named: connections/receive-invitation for the second ACA-Py agent. If successful, you will see a response message shown in figure 8.

figure 8 — Holder agent’s API call to receive an invitation

Now, if you check the logs of the two ACA-Py agents in the two VMs, you should see a trust ping auto populated in both agents (see figures 9 and 10). This is because when running an ACA-Py agent, if you completely follow Part III, an auto-ping-connection flag is turned on. Since we’ve also turned on the other two flags auto-accept-invites and auto-accept-requests, the connection establishment process doesn’t require any manual checks.

figure 9— a trust ping is received on the first agent

figure 110— a trust ping received on the second agent

Until now, the one-time communication channel between the two ACA-Py agents have been established.

You can now call a GET API named: /connections on both agents (see figures 11 and 12).

figure 11 — Issuer agent’s connection list

figure 12 — holder agent’s connection list

Note: for the issuer agent (the one sends out an invitation) and the holder agent (the one receives an invitation), their connection_id are different.

You can also call a GET API named: /wallet/did for both agents. You will see the issuer agent has two DIDs: (1) the public DID and (2) the private DID (the one used for channel connection), see figure 13. The holder agent only has one private DID (see figure 14).

figure 13 — issuer agent has two DIDs, one public and one private

figure 14 — holder agent has only 1 private DID used for connection

You can even call a POST API named: /connections/{connection_id}/send-message and put a JSON payload in the body in both agents to explicitly send messages to the other side (see figure 15), and you can verify this message being received on the holder agent’s log (see figure 16).

figure 15 — Call an API on the issuer agent to send a message to the holder agent

figure 16 — Log in the holder agent showing this message has been received

Conclusion

By following this Part IV, you should be able to set up a one-time connection channel between two agents and understand how you can verify the connection is ready by sending messages from one agent to the other. The only downside the approach used is establishing this channel between two agents is currently a manual process. This manual process makes sense here, as there is no such a channel existing between two agents yet. One would expect this process to be automated for simplicity, but how to make this happen is still without a clear solution to the best of my knowledge.

Nevertheless, I still see this manual process would be required and useful in production-level environments, especially across multi-companies/organisations. At a corporate level, the system admins who receive an invitation from agents belonging to other corporates, they should have do some manual checks first to make sure this agent-level invite does come from an agent of a trusted corporate/partner (e.g. by calling the trusted company’s system admins/business representatives who’s responsible of hosting and maintaining the agents sending out this invite).

Part V will show you how to do the credential schema and definition creation. See you there.