Manage DIDs

Manage the DIDs which are owned by the Edge Agent for usage in DI protocols

Many DI protocols require the agent to provide the DID which they want to use for the interaction. Some Edge Agent interactions automatically handle this usage of DIDs in protocols. However in some protocols it is more suitable for the SDK consumer to be explicit about the DID/s they want to use. When this is the case, the SDK's DidsModule can be used to manage the DIDs owned by the agent.

The functionality of the DidsModule is accessed via the agent's fields: agent.dids.

Create DIDs

To create and store DIDs with the Edge Agent SDK, the createDid API can be used. This API takes a CreateDidOptions type, which has different data variants for the different DID methods supported. On success, this API returns a DidInformation data object with the details of the DID that was created.

For instance, to create a did:key DID:

Swift

let agent: SudoDIEdgeAgent

do {
    let createdDid = try await agent.dids.createDid(
        options: .didKey(keyType: .ed25519)
    )
} catch {
    // handle error
}

Kotlin

val agent: SudoDIEdgeAgent

try {
    val createdDid = agent.dids.createDid(
        options = CreateDidOptions.DidKey(
            keyType = DidKeyType.ED25519
        )
    )
} catch (e: DidsModule.CreateDidException) {
    // handle error
}

In the above example, the DID's cryptographic key will be generated using the agent's internal software-based key management. For hardware-based key management and other custom options, see Create a DID backed by a Custom Cryptography Provider.

See the Standards and Protocols section for a list of DID methods supported for creation by the Edge Agent SDK.

Get full DID Information by ID

To retrieve the current full DidInformation of a specific DID owned by the agent, the getById API can be used. If a DID cannot be found by the given identifier, then null is returned:

Swift

let agent: SudoDIEdgeAgent

do {
    let did = try await agent.dids.getById(did: "did:example:123")
} catch {
    // handle error
}

Kotlin

val agent: SudoDIEdgeAgent

try {
    val did = agent.dids.getById("did:example:123")
} catch (e: DidsModule.GetException) {
    // handle error
}

Delete a DID

Similarly, a DID in the wallet can be easily deleted via the deleteById API:

Swift

let agent: SudoDIEdgeAgent

do {
    try await agent.dids.deleteById(did: "did:example:123")
} catch {
// handle error
}

Kotlin

val agent: SudoDIEdgeAgent

try {
    agent.dids.deleteById("did:example:123")
} catch (e: DidsModule.DeleteException) {
    // handle error
}

Updating the Storage Metadata of a DID

DidInformation objects contain storage metadata (local only) that can be controlled by SDK consumers, allowing custom information to be attached to each DidInformation . It also allows custom listing functionality to be leveraged.

Each DidInformation contains a list of RecordTag (DidInformation.tags) attached to it, where a RecordTag is simply a name-value pair stored with the record.

The tags on a DidInformation can be replaced or updated by using the updateDid API, and providing a new set to update. This will replace the current set of tags. An example follows:

Swift

let agent: SudoDIEdgeAgent

// add a 'category' of 'work' to this DID, and a 'priority' of '1'
let update = DidUpdate(tags: [
    RecordTag(name: "category", value: "work"),
    RecordTag(name: "~priority", value: "1")
])

do {
    try await agent.dids.updateDid(
        did: "did:example:123",
        didUpdate: update
    )
} catch {
    // handle error
}

Kotlin

val agent: SudoDIEdgeAgent

// add a 'category' of 'work' to this DID, and a 'priority' of '1'
val update = DidUpdate(
    tags = listOf(
        RecordTag("category", "work"),
        RecordTag("~priority", "1")
    )
)

try {
    agent.dids.updateDid("did:example:123", update)
} catch (e: DidsModule.UpdateException) {
    // handle error
}

Like most data in the wallet, RecordTag will be stored encrypted. Unless, the tag name is prefixed with ~, then the tag value will be stored unencrypted. Storing a tag value as unencrypted will allow some additional listing queries to be performed (see below).

Listing DIDs

To list all DIDs owned by the agent, the listAll API can be used:

Swift

let agent: SudoDIEdgeAgent

do {
    let dids: [DidInformation] = try await agent.dids.listAll(
        options: nil
    )
} catch {
    // handle error
}

Kotlin

val agent: SudoDIEdgeAgent

try {
    val dids: List<DidInformation> = agent.dids.listAll()
} catch (e: DidsModule.ListException) {
    // handle error
}

Filtered Listing

More complicated DidInformation list queries can also be achieved by utilizing the ListDidsFilters filter. These filters allow for filtering by DID Method, Key Types and record tags.

To filter by tags applied to the DidInformation (i.e. applied via the update API), the tagFilter field of ListDidsFilters should be used. This field takes a String in compliance with a Wallet Query Language (WQL) Query.

Continuing from the example in the Update section:

Swift

let agent: SudoDIEdgeAgent

// WQL Query, filter for 'category' == 'work'
let wqlQuery = "{ \"category\": \"work\" }"
let filters = ListDidsFilters(tagFilter: wqlQuery)
let options = ListDidsOptions(filters: filters)

do {
    let workDids = try await agent.dids.listAll(options: options)
} catch {
    // handle error
}

// WQL Query, filter for priority < 2 (e.g. 'high' priority items)
let wqlQuery = "{ \"~priority\": { \"$lt\": \"2\" } }"
let filters = ListDidsFilters(tagFilter: wqlQuery)
let options = ListDidsOptions(filters: filters)

do {
    let highPriorityDids = try await agent.dids.listAll(options: options)
} catch {
    // handle error
}

Kotlin

val agent: SudoDIEdgeAgent

// WQL Query, filter for 'category' == 'work'
val wqlQuery = """{ "category": "work" }"""
val filters = ListDidsFilters(tagFilter = wqlQuery)
val options = ListDidsOptions(filters)

try {
    val workDids = agent.dids.listAll(options)
} catch (e: DidsModule.ListException) {
    // Handle exception
}

// WQL Query, filter for priority < 2 (e.g. 'high' priority items)
val wqlQuery = """{ "~priority": { "${"$"}lt": "2" } }"""
val filters = ListDidsFilters(tagFilter = wqlQuery)
val options = ListDidsOptions(filters)

try {
    val highPriorityDids = agent.dids.listAll(options)
} catch (e: DidsModule.ListException) {
    // Handle exception
}