# General DIDComm v2 Library Spec

The purpose of this doc is to provide a scratch space where we can wrestle with what we'd like to see in [Project Gemini](https://github.com/sicpa-dlab/didcomm-gemini)'s efforts to provide libraries that offer support for DIDComm. We know that implementations have to conform to the spec; what we need to decide is what mental models, algorithms, and data structures we want our libraries to use to accomplish that goal. Will they be fancy or simple, high-level or low-level?

## Key Assumptions

1. The libraries that support DIDComm in Python are not going to be identical in scope, named constructs, or usage patterns to the ones for Go, Rust, JavaScript, Java, or any other language. Each library will be idiomatic and will have slightly different needs. Some may be function-oriented, others object-oriented. They won't share a single source ancestry or common release schedules. However, the supported features should be similar.
2. We want libraries with minimal dependencies. The form factor should be standalone libraries with DIDComm features only, not heavy frameworks. We are NOT trying (directly) to help build agents -- only to implement the DIDComm spec so anybody can use DIDComm easily.
3. Libraries will be published using standard package manager(s) for their respective languages: `pypi`, `npmjs`, `maven`, `crates.io`, etc.
4. DIDComm depends on DIDs -- but DID resolution is a complex topic unto itself. We will keep our libraries simple by providing a DID resolution *interface* in each library, plus two standard implementations of that interface -- one for peer DIDs, and one for the universal resolver. Fancier impls can be plugged in, but won't be provided by the libraries.
5. The libraries are not responsible for transmitting messages over a transport, only for preparing them to be transmitted.
6. It must be possible to use these libraries to carry on multiple simultaneous interactions between Alice and Bob in parallel. (We'd prefer that the libraries not encourage statefulness -- but if they do, the statefulness MUST NOT constrain interactions to an artificial behavior pattern that is drastically simpler than DIDComm's supported behavior scope.)
7. Massively efficient asynchronicity in DID lookup (e.g., fancy, threadsafe caching) is not important. We might want to use a library to do a few DID resolutions in parallel (in which case caller provides threads to do so) -- but the main parallelism associated with these libraries will be parallel sending and receiving over the network, which is out of scope. We don't need callbacks or futures for our functions.

## Required features

1. Support for Ed25519 and secp256k1. (Other types of crypto may also be desirable, but these are the two highest priorities.)

3. Encrypt a message from Alice to Bob and maybe Carol. (1 sender, >1 recipients; for a given recipient, maybe >1 keys). Function declaration might be something like `encrypt(bytes, from_private_key_for_DID, to_DIDs[]) -> encrypted_envelope`. This function would resolve each DID in `to_DIDs`, find all key agreement keys for the DID, and add those keys to the composite list of recipients. This function would need to be called repeatedly to wrap a message like an onion for a full DIDComm route.

2. Decrypt a message. Function declaration might be something like `decrypt(bytes, for_private_key_for_DID, assumed_sender_DID) -> decrypted_payload`. This function would confirm that the message came from `assumed_sender_did`, and then, if the message can be decrypted, return `decrypted_payload`. Might also need to return a list of other recipients?

3. Sign a message (before encrypting it).
4. Verify a signature on a message (after decrypting it).
5. Resolve a DID to a DID doc, possibly at a point in time or a snapshot version. This is where the DID resolution interface is exposed. Possible signature: see Universal Resolver's interface.
6. Attach a stream of bytes to a plaintext DIDComm message. `attach(message, bytes, mime_type, download_uri?)`
7. Fetch bytes attached to a plaintext DIDComm message.