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

Kotlin

// The url commonly comes from the result of scanning a QR code.
val invitation = OutOfBandInvitationMessage.fromUrl(url)
// Or if you have the message in json already
val invitation = OutOfBandInvitationMessage.fromJsonString(str)

React Native

// parses the URL to a json string
const invitation: string = agent.outOfBand.parseInvitation(invitationUrl)

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

Kotlin

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

// Waits for the record to be in the completed state
agent.events.getDidExchangeEvents?.events?.first { event ->
    if (records.didExchangeRecord.id != event.didExchangeRecord.id) {
        event.didExchangeRecord.state == DidExchangeState.Completed
    }
}

React Native

// Takes the json formatted string for the invitation
const records = await agent.outOfBand.receiveInvitation(invitation)

const removeListener = agent?.events.registerDidExchangeHandler((event) => {
  if (event.didExchangeRecord.id === records.didExchangeRecord.id && event.didExchangeRecord.isReady) {
    console.log("Connection complete")
    removeListener()
  }
})

While it is not recommended to disable auto acceptance, manually accepting a connection is also an option.

Manually accepting a connection (autoAcceptConnection = false)

Kotlin

// 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)

React Native

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

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

NOTE: In the above example you technically have two instances of the didExchange record, one in the records variable and one in the exchangeRecord variable. Since records can be updated asynchronously, always use the most recently returned value or fetch the record by ID if any operations have been done that could affect the Agent's records.

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".

Kotlin

// This is a suspend function in Kotlin
val contacts: List<DidExchangeRecord> = agent.didExchange.getAll()

React Native

const contacts = await agent.didExchange.getAll()

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, and autoAccept.

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.

Removing a connection

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).

Kotlin

val contacts = agent.didExchange.getAll()
// Deleting the first contact in the list
agent.didExchange.deleteById(contacts[0].id)

React Native

const contacts = await agent.didExchange.getAll()

await agent.didExchange.deleteById(contacts[0].id)