Architecture Update

[jakubkoci]

As a developer, I want to separate parts of the framework into a standalone module with clear boundaries (API) so that it fits in my head, I can understand a smaller amount of code to maintain and enhance it.

Folder structure:

• core
  • agent
    • Agent
    • AgentDependencies
  • didcomm
    • decorators
    • repository
      • DidCommMessageRecord, DidCommMessageRepository
    • messages
      • AgentMessage
      • AckMessage
      • BaseMessage
    • Dispatcher, EnvelopeService, Events, Handler, MessageReceiver, MessageSender, TransportService
  • modules -> protocols: The main idea is to separate what represents protocol and what does not.
    • basic-message
    • credentials
    • proofs
    • Out-of-band, DidExchange, Connections, Routing, Trust Ping, Discovery, Problem Report
  • common (shared?): This can be something shared across the framework but also part of public API. Other candidates are dids, crypto, ledger, wallet maybe transport.
    • errors
    • AgentConfig
  • infrastructure: I grouped it as an infrastructure but it can stay at the higher level for now.
    • cache
    • crypto
    • dids
    • events
      • EventEmitter
      • message queue
    • indy
    • logger
    • ledger
    • storage
    • transport
    • utils: There are items with quite a lot of different functionality and responsibility. Ideally, we should distinguish between general-purpose and domain-specific utilities
    • wallet
  • migration: I think it can be convenient to call public API, so I would put it at the higher level
• platforms
  • node
  • react-native

Ideally, I would like to have didcomm module without dependency on other protocols. The problem is with connections. We are using connections inside objects I want to move to didcomm. But, connection protocols, like any other protocol, need to send a message via didcomm module. I have the following solutions/approaches in my mind:

1. Moving DIDComm related protocols (Out-of-band, DidExchange, Connections, Routing, Trust Ping, Discovery, Problem Report) from protocols to didcom/protocols. That would allow to hide implementation details and introduce strict one-way dependency from protocols to didcomm/protocols. Then, we can call didcomm.sendMessage(message, toDid, fromDid) from other modules.

The problem is it creates a concept where there are some protocols inside didcomm, but the rest of the protocols are just in protocols. Should that be rather organized in a way credentials/protocols, proofs/protocols? How would anyone understand where to put another type of protocol and how to name it?

2. Removing dependency connections -> dids, adding dependency dids -> connections and resolve DIDDocument needed inside didcomm via dids module.

3. Eventually add some Connections interface to didcomm and implement it inside connections.

The concept of common vs. infrastructure is still questionable. Does it bring any benefit to separate those? I like the idea when infrastructure represents something without any dependency inwards (to other parts of the framework).

Explanation of responsibilities of protocol implementation

• Handler: A handler is responsible for validation of the state of the agent before it passes the message and its context to the protocol method
• Protocol: A protocol is responsible for validating message and updating the state of the agent based on the message
• Service: A service is responsible for CRUD operations with Record plus helper function to validate and update the state of the Record.
• Repository: A repository is responsible for the persistence of the Record.

Other small bits to reconsider:

• Types in core/src/types.ts have dependencies to a lot of other parts of the framework, but it should be rather a leaf.
• Update record state after the message has been successfully sent
• Use more queries than specific methods
• Use only const enum
• Flavored types for Did, Keys instead of strings

[TimoGlastra]

This sounds interesting @jakubkoci! Maybe we can spend some time on it during the WG call tomorrow and derive actionable issues from it!

Some initial thoughts on your points:

The problem is it creates a concept where there are some protocols inside didcomm, but the rest of the protocols are just in protocols.

I think this is exactly how didcomm v2 works, and therefore not a bad thing. By defining a select number of protocol as core protocols, we can keep the core didcomm functionality 'lean', while allowing for extension in non-core protocols. The DIDComm v2 spec defines a few protocols as native to the spec, so we could easily include those in the didcomm package.

Removing dependency connections -> dids, adding dependency dids -> connections and resolve DIDDocument needed inside didcomm via dids module.

TBH my thoughts would be the direct opposite of this. Although connections are a core part of DIDComm v1, there's no notion of connections in didcomm v2. There's just dids, which form a relation. So it wouldn't make sense to me to add a dependency from dids to conenctions.

I do agree though that a didcomm module that has a method didcomm.sendMessage(message, toDid, fromDid) makes a lot of sense.

[swcurran]

TBH my thoughts would be the direct opposite of this. Although connections are a core part of DIDComm v1, there's no notion of connections in didcomm v2. There's just dids, which form a relation. So it wouldn't make sense to me to add a dependency from dids to conenctions.

Really? AFAIK the way you establish connections in DIDComm V2 is different than in DIDComm V1 -- e.g. it can be done as part of sending a message (0-RT) vs. as using a specific protocol. However, AFAIK, there is still the concept of a connection. You still have to track other metadata about the DID, including the DIDs each side uses in communicating with the other.

How do you see it?

[TimoGlastra]

As you don't need a connection anymore to send a message (just two dids is enough), I think a connection can become something optional. Sure it's useful and probably something we want to keep. But because it's something optional I would say it's something separate from dids and didcomm, but more an agent feature.

Let's say we have the following code. By sending a message like this, the didcomm module and the dids module don't need to know about the connection. The sender did and the recipient did is al it needs to know.

await agent.didcomm.sendMessage(message, connection.theirDid, connection.myDid)

You probably still want to know whether a relationship (connection) exists when receiving messages so you know the combination of dids is known to you, but is something optional that could be built on top of the didcomm module

In AFJ we don't check whether the connection is active before sending a message to the message handler. Then in the handler of a message you can choose to assert a relation exists (currently using messageContext.assertReadyConnection())

BTW I asked this in the DIDComm user group discord, to see what they think: https://discord.com/channels/900385725462229022/911224279885033533/969170888647905310