---
# System prepended metadata

title: DIDComm Module

---

# DIDComm Module

## Constraints

- Recipient DID Doc
  - must have DIDCommMessaging service entry
  - must have at least one entry in keyAgreementKey of type X25519
  - if service entry contains a mediator, messages will be first encrypted to the recipient(s) and then wrapped in a encrypted enveloped for the mediator (ie forward message)

- Flow
  - DID(Alice) -> Mediator(Bob) <-> DID(Bob)
  - DID(Bob) -> Mediator(Alice) <-> DID(Alice)
 
- Transport protocol is HTTPS

- (out of scope) mapping of ETH account onto DID but we will work on some mapping (aka `agent.queryDID({ ethereumAccount: "0xabcd..."})`) as part of our Messaging initiative:
  - ETH Account -> DID, through ERC1056, CAIP10-Links
  - Other mappings will be possible and pluggable

- Storage of messages
  - ???

- What types are required?
  - SDR?
  - Issuance?
  - Other things?

## API

### Flows

#### SDR Flow between Serto Agents in the cloud

- Alice to Bob, both did:ethr, no service endpoints and no encryption keys
- Alice gets Bob's DID and notices that there is no encryption key and endpoint
- Alice asks Serto Search for a VC from Bob that tells her Bob's enc key and endpoint
- Alice sends a DIDComm Message to Bob encrypted to that key and to that endpoint

### Create DIDComm Message

Contains the following fields:
- type, e.g., veramo.io/sdr/request/vx
- to, from fields
- body, the actual protocol message

### Pack DIDComm Message

```javascript=
const jweMessage = await agent.packDIDCommMessage(kid, skid, message)
```

### Recieving DIDComm Message

- decrypt
- validate

### Send DIDComm Message

```javascript=
agent.sendDIDCommMessage(recipientDids, message, 
  options: { 
    recipientDids: [ "did1", "did2" ],
    mode: "authcrypt" | "anoncrypt", ... 
    endpoint: "https:serto.io/mediator",
    encryptionKey: {
      ...    
    }
  }
)
```

### what does sending really do on top of packing?

- if sendDIDComMMessage fails, why not just send to static endpoint? and then call handleMessage at the recipient?

### did:ethr initial-state only semi solves the problem
- how does serto search get the initial-state? or the sender?

did:ethr:0xabacd?initial-state=did-doc-entries
did:ion?

sendMessage()


```javascript=
agent.sendDIDCommMessage(recipientDids, message, 
  options: { 
    recipientDids: [ "did1", "did2" ],
    mode: "authcrypt" | "anoncrypt", ... 
  }
)
```

### Get DIDComm Messages by Type

```javascript=
agent.dataStoreORMxyz(...)

or

// WIP: by Simonas
// agent.dataStoreXyz(...)
```