Connections

Creating a Connection

All connections are made through the Out of Band protocol using the Out of Band module on the Agent.

First you have to get an Out of Band invitation. This is done using one of two methods: either through a QR code that resolves to a URL (most common), or from a JSON object in the form of a string.

Parsing the invitation

// The url commonly comes from the result of scanning a QR code.
val invitation = OutOfBandInvitationMessage.fromUrl(url)

// parses the URL to a json string
const invitation: string 

Once you have the Out of Band invitation you will have the Agent accept the invitation. The receiveInvitation function has many options but to automatically make a connection with the provided invitation you can supply just the invitation like the examples below.

Receiving and waiting for a completed connection

// Completed connection status may or may not be done after this call
val records = agent.outOfBand.receiveInvitation(invitation)

// Takes the json formatted string for the invitation
const records = await

Manually accepting a connection (autoAcceptConnection = false)

// returns references to records needed to complete connection
val records = agent.outOfBand.receiveInvitation(invitation, autoAcceptConnection = false)

// Connection guaranteed to be completed after this call
val exchangeRecord = agent.didExchange.requestConnection(records.didExchangeRecord!!.id, records.outOfBandRecord.id)

const record = await agent.outOfBand.receiveInvitation(invitation, false)

const exchangeRecord = await agent.didExchange.requestConnection(records.didExchangeRecord!!.id, records.outOfBandRecord.id)

Retrieving and using the didExchange records

Once a connection has been made through the DidExchange protocol the agent will keep a record which holds information about the established connection. A list of all connections can be retrieved and used to create a "contact list".

The DidExchange record itself has several properties derived when making a connection based on information provided from the agent that you are connecting to. Some commonly used properties: did, state, role, theirDid, theirLabel, createdAt, updatedAt, alias, threadId, mediatorId, outOfBandId, invitationDid

Some properties (like createdAt, updatedAt, and id) are present on all records. With DidExchangeRecords you would likely use theirLabel or alias to create a contact card item for displaying the connection. Other properties like role and state can be used to filter connections to find a specific connection or locate ones that failed or still need to be accepted after processing the invitation.

If you no longer want to have a connection with another agent you can delete the DidExchangeRecord. If you need to reconnect you will have to receive another invitation from the agent, or in some instances invitations can be reused (NOTE: single-use invitations can only be used by one agent while multi-use invitations can be used by multiple).