Overview
The DIDComm module provides APIs for working with DIDComm protocols, enabling secure, encrypted messaging between agents.
Available when the DIDComm module is registered:
import { DidCommModule } from '@credo-ts/didcomm'
import { Agent } from '@credo-ts/core'
const agent = new Agent({
// ...
modules: {
didcomm: new DidCommModule(),
},
})
await agent.initialize()
// Access DIDComm APIs
const connections = agent.didcomm.connections
const credentials = agent.didcomm.credentials
const proofs = agent.didcomm.proofs
ConnectionsApi
Manage DIDComm connections between agents.
acceptOutOfBandInvitation()
Accept an out-of-band invitation to establish a connection.
// Parse invitation
const invitation = await agent.didcomm.oob.parseInvitation(invitationUrl)
const oobRecord = await agent.didcomm.oob.receiveInvitation(invitation)
// Accept invitation
const connectionRecord = await agent.didcomm.connections.acceptOutOfBandInvitation(
oobRecord,
{
label: 'My Agent',
protocol: DidCommHandshakeProtocol.DidExchange,
autoAcceptConnection: true,
}
)
console.log('Connection:', connectionRecord.id)
outOfBandRecord
DidCommOutOfBandRecord
required
Out-of-band record from received invitation
Configuration:
label: Agent labelprotocol: Handshake protocol (‘did-exchange’ or ‘connections’)autoAcceptConnection: Auto-accept connectionalias: Optional connection aliasrouting: Optional routing configuration
Promise<DidCommConnectionRecord>
acceptRequest()
Accept a connection request (as inviter).
const connectionRecord = await agent.didcomm.connections.acceptRequest(
connectionId
)
Promise<DidCommConnectionRecord>
acceptResponse()
Accept a connection response (as invitee).
const connectionRecord = await agent.didcomm.connections.acceptResponse(
connectionId
)
Promise<DidCommConnectionRecord>
sendPing()
Send a trust ping to test connection.
const message = await agent.didcomm.connections.sendPing(connectionId, {
responseRequested: true,
})
responseRequested: Request response pingwithReturnRouting: Use return routing
Promise<TrustPingMessage>
getAll()
Retrieve all connections.
const connections = await agent.didcomm.connections.getAll()
Promise<DidCommConnectionRecord[]>
getById()
Retrieve connection by ID.
const connection = await agent.didcomm.connections.getById(connectionId)
Promise<DidCommConnectionRecord>
findAllByQuery()
Find connections by query.
const connections = await agent.didcomm.connections.findAllByQuery(
{ state: DidCommConnectionState.Completed },
{ limit: 10 }
)
query
Query<DidCommConnectionRecord>
required
Query object
Query options (limit, offset)
Promise<DidCommConnectionRecord[]>
deleteById()
Delete a connection.
await agent.didcomm.connections.deleteById(connectionId)
Promise<void>
CredentialsApi
Issue and receive credentials using DIDComm protocols.
offerCredential()
Offer a credential to a connection (issuer).
const credentialRecord = await agent.didcomm.credentials.offerCredential({
connectionId,
protocolVersion: 'v2',
credentialFormats: {
anoncreds: {
credentialDefinitionId,
attributes: [
{ name: 'name', value: 'Alice Smith' },
{ name: 'degree', value: 'Bachelor of Science' },
],
},
},
autoAcceptCredential: AutoAcceptCredential.ContentApproved,
})
Protocol version (‘v1’ or ‘v2’)
options.credentialFormats
Format-specific credential data
options.autoAcceptCredential
Auto-accept behavior
Promise<DidCommCredentialExchangeRecord>
acceptOffer()
Accept a credential offer (holder).
const credentialRecord = await agent.didcomm.credentials.acceptOffer({
credentialExchangeRecordId,
autoAcceptCredential: AutoAcceptCredential.Always,
})
options.credentialExchangeRecordId
Credential exchange record ID
options.credentialFormats
Format-specific options
Promise<DidCommCredentialExchangeRecord>
acceptRequest()
Accept a credential request and issue credential (issuer).
const credentialRecord = await agent.didcomm.credentials.acceptRequest({
credentialExchangeRecordId,
credentialFormats: {
anoncreds: {
// Final credential values
},
},
})
options.credentialExchangeRecordId
Credential exchange record ID
options.credentialFormats
Format-specific credential data
Promise<DidCommCredentialExchangeRecord>
acceptCredential()
Accept a received credential (holder).
const credentialRecord = await agent.didcomm.credentials.acceptCredential({
credentialExchangeRecordId,
})
options.credentialExchangeRecordId
Credential exchange record ID
Promise<DidCommCredentialExchangeRecord>
getAll()
Retrieve all credential exchange records.
const records = await agent.didcomm.credentials.getAll()
Promise<DidCommCredentialExchangeRecord[]>
getById()
Retrieve credential exchange record by ID.
const record = await agent.didcomm.credentials.getById(credentialExchangeRecordId)
credentialExchangeRecordId
Credential exchange record ID
Promise<DidCommCredentialExchangeRecord>
ProofsApi
Request and present proofs using DIDComm protocols.
requestProof()
Request a proof from a connection (verifier).
const proofRecord = await agent.didcomm.proofs.requestProof({
connectionId,
protocolVersion: 'v2',
proofFormats: {
anoncreds: {
name: 'Employment Verification',
version: '1.0',
requested_attributes: {
name: {
name: 'name',
restrictions: [{ cred_def_id: credDefId }],
},
},
requested_predicates: {
age: {
name: 'age',
p_type: '>=',
p_value: 18,
restrictions: [{ cred_def_id: credDefId }],
},
},
},
},
})
Protocol version (‘v1’ or ‘v2’)
Format-specific proof request
Promise<DidCommProofExchangeRecord>
acceptRequest()
Accept a proof request and send presentation (prover).
// Get credentials for request
const credentials = await agent.didcomm.proofs.getCredentialsForRequest({
proofExchangeRecordId,
})
// Select credentials
const selectedCredentials = await agent.didcomm.proofs.selectCredentialsForRequest({
proofExchangeRecordId,
})
// Accept and send proof
const proofRecord = await agent.didcomm.proofs.acceptRequest({
proofExchangeRecordId,
proofFormats: selectedCredentials.proofFormats,
})
options.proofExchangeRecordId
Proof exchange record ID
Format-specific proof data
Promise<DidCommProofExchangeRecord>
acceptPresentation()
Accept and verify a received presentation (verifier).
const proofRecord = await agent.didcomm.proofs.acceptPresentation({
proofExchangeRecordId,
})
if (proofRecord.state === DidCommProofState.Done) {
console.log('Proof verified successfully')
}
options.proofExchangeRecordId
Proof exchange record ID
Promise<DidCommProofExchangeRecord>
getCredentialsForRequest()
Get available credentials for a proof request.
const credentials = await agent.didcomm.proofs.getCredentialsForRequest({
proofExchangeRecordId,
})
console.log('Available credentials:', credentials)
options.proofExchangeRecordId
Proof exchange record ID
Promise<GetCredentialsForProofRequestReturn>
selectCredentialsForRequest()
Automatically select credentials for a proof request.
const selected = await agent.didcomm.proofs.selectCredentialsForRequest({
proofExchangeRecordId,
})
options.proofExchangeRecordId
Proof exchange record ID
Promise<SelectCredentialsForProofRequestReturn>
getAll()
Retrieve all proof exchange records.
const records = await agent.didcomm.proofs.getAll()
Promise<DidCommProofExchangeRecord[]>
getById()
Retrieve proof exchange record by ID.
const record = await agent.didcomm.proofs.getById(proofExchangeRecordId)
Promise<DidCommProofExchangeRecord>
Complete Example
import { Agent, AutoAcceptCredential } from '@credo-ts/core'
import { DidCommModule, DidCommHandshakeProtocol } from '@credo-ts/didcomm'
// Setup agents
const issuer = new Agent({
// ...
modules: { didcomm: new DidCommModule() },
})
const holder = new Agent({
// ...
modules: { didcomm: new DidCommModule() },
})
await issuer.initialize()
await holder.initialize()
// Create out-of-band invitation
const oobRecord = await issuer.didcomm.oob.createInvitation({
label: 'Issuer Agent',
handshakeProtocols: [DidCommHandshakeProtocol.DidExchange],
})
const invitationUrl = oobRecord.outOfBandInvitation.toUrl({ domain: 'https://example.com' })
// Holder accepts invitation
const holderOobRecord = await holder.didcomm.oob.receiveInvitation(invitationUrl)
const connection = await holder.didcomm.connections.acceptOutOfBandInvitation(
holderOobRecord,
{
label: 'Holder Agent',
protocol: DidCommHandshakeProtocol.DidExchange,
autoAcceptConnection: true,
}
)
// Wait for connection to be established
await holder.didcomm.connections.returnWhenIsConnected(connection.id)
// Issue credential
const credentialRecord = await issuer.didcomm.credentials.offerCredential({
connectionId: oobRecord.connectionId,
protocolVersion: 'v2',
credentialFormats: {
anoncreds: {
credentialDefinitionId,
attributes: [
{ name: 'name', value: 'Alice Smith' },
{ name: 'degree', value: 'Bachelor of Science' },
],
},
},
autoAcceptCredential: AutoAcceptCredential.ContentApproved,
})
// Request proof
const proofRecord = await issuer.didcomm.proofs.requestProof({
connectionId: oobRecord.connectionId,
protocolVersion: 'v2',
proofFormats: {
anoncreds: {
name: 'Degree Verification',
version: '1.0',
requested_attributes: {
degree: {
name: 'degree',
restrictions: [{ cred_def_id: credentialDefinitionId }],
},
},
},
},
})