# conceptual.storage

As we integrate [UCAN][]s in .storage services we find [DID][]s used for lot of different things. Sometimes same exact DID can play many different roles which can be very confusing especially when reasoning through centralized systems perspective.

This document is an attempt to conceptualize ideas by providing few mental metaphors for the things DIDs are used.

### ~~User~~ Client DID

We often talk about user or a client DID interchangeably. However we do not actualy have a concept of User DID, that is because user may operate multiple clients across multiple devices, each one with own unique DID.

This may sound wierd, but we don't even ask users to register all these client DIDs with their account, we only require registering one although they certainly can register more than one.

If this feels wierd that is because you're still thinking about these DIDs as a user DIDs which is both inaccuarte and bad way to conceptualize. Before we explore a better mental model, we need to conceptualize accounts first.

### Account DID

In order to provide service we need to do some accounting. To help with that we conceptualize some _set of client DIDs_ as an account. Naturally to create an account usern needs to register some client DID.

When new user registers a client DID we want some assurance that we will have a way to contacting them if that becomes necessary (e.g. if they abuse our terms of service). For this reason registering new client DID requires proof of email ownership, which is just a fancy way to say we ask user for an email where we send cryptographic proof of verification they need to provide on registration.

Earlier we said user does not need to register every single client DID, but they could if they wanted to. We'll get into how that might be useful later, but before lets go into how.

So if user wants to register another client DID, they could go through the same flow as with first one. However since we already know one client DID of the user we could simply allow that client to add another DID without having to go through the email verification step. And that is more or less what we do - we allow two client DIDs to be linked _(as long as one of delegates permission to the other to be linked)_. When two client DIDs are linked new DID is just added to the set representing a user account.

:::info
You may wonder what happens if client DIDs been linked belong to two different accounts. Since account is just a set of DIDs we just joint two sets into joint account. Or put it differently accounts merge.
:::

### Users ≠ Accounts

So far we have been talking about a user with one or more client DIDs that represen an account and this time it may seem that user = account. However that is also inaccurate, it is not unreasonable to allow group of users to have a shared account (our team shares company account, but we all have different users)

### Conceptualizing client DID

We talked a lot how to not think about things, now lets talk about how we might. We have established that client DID is some unique ID on some users device. We also established that not all such DIDs need to be registered, but some do (at least one per account). Lets explore how ones that are registered differnt from the ones that do.

#### Methaphors

One way to think about registered DID is to think about it as "directory" you're sharing with a service like dropbox or an icloud or a google drive. When you put some files in that directory it magically gets synced across your devices where you have corresponding software setup and wired. And the service you use bills you according to amount of files you drop there.

So you can think of some client DID as some directory on that device. In order to sync it with others you need to wire it with dropbox like service which is conceptually equivalent of our client DID registration. User may also have multiple such directories which would be equivalent of registering multiple client DIDs.

Now lets stretch this methaphor bit further, dropbox and alike allow you to share directories with friends and family too. In our world this translates into delegating `"store/*"` capabilities with that client DID that we decided to think of as this shared directory.

You might be wondering what that other client DIDs represent in this model. I'm failing to stretch this methaphor any further, so we'll have to use some imagination. Lets say that this shared directory of ours is known by client DID it was created on, but on every device it is synced on it is also assigned separate unique DID. That is more or less those unregistered DIDs are and just like our directory some can correspond to other devices and some to devices of our friends or family _(although unlike dropbox and alike we don't ask your friends and family to create an account with use, it's more like hackmd you share they can read / write)_

:::spoiler
Fun fact, most likely dropbox and others do actually have unique ID per replica because distributed systems need to track source of changes in order to reconsile.
:::

### Same client DID across multiple services

If you got this far, congrats this is where fun part starts. Imagine you need to share our methaphorical directory with group of friends where some have Dropbox but others will only accept iCloud. You can just wire same directory with both services and share away! That is conceptually no different from registering same client DID with both web3.storage and nft.storage.

You'd get billed by both services, but you did not have to exclude some of your friends. And I would expect same to be true with our .storage services. If you don't want to pay double, just don't register same DID.

If you are still not convinced and think that no user should send separate requests to both .storage requests think how would you feel if that mataphorical directory appeared to have different files to your dropbox friends from your iCloud friends.

More seriously though we're building distributed system into which different actors and services could plug in. Publish / subscribe semantics fit a lot better here than request / response. In consider web3-name <-> IPNS where when you update web3-name change is replicated through IPNS network. It's not unreasonable to imagine our metaphorical directories having web3 / IPNS names corresponding to it's DID and it would be bizzare if it resolved to a different content across web3.storage, nft.storage or our competitor.storage.

Put it differently DID should represent the source of truth (as in what's in that directory) and services should just subscribe and act on changes as opposed to making client call up each service individually to let notify them of a change.

[UCAN]:https://github.com/ucan-wg/spec/
[DID]:https://w3c-ccg.github.io/did-method-key/