From 049fc08e2ed761560d3b44a9498e4afda2f479b6 Mon Sep 17 00:00:00 2001 From: Vasco Santos Date: Fri, 19 Jan 2024 18:03:25 +0100 Subject: [PATCH] docs: add w3 space basic spec (#93) Adds basic space spec. While at first considered to add it to `w3-account` or `w3-access`, I realized that account has a specific focus on high level account with multiple spaces, while access focus on "aggregating and managing delegated capabilities across agents". Therefore, ended up with new spec document to reflect the basics of a space protocol. It is complemented by `w3-account` and `w3-provider` on how to integrate account and providers, while in its basic form adds wire protocol for the space specific capabilities that do not fall under the umbrella of `account` and `provider`. --- w3-space.md | 77 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) create mode 100644 w3-space.md diff --git a/w3-space.md b/w3-space.md new file mode 100644 index 0000000..59c9950 --- /dev/null +++ b/w3-space.md @@ -0,0 +1,77 @@ +# Space + +![status:reliable](https://img.shields.io/badge/status-reliable-green.svg?style=flat-square) + +## Editors + +- [Vasco Santos], [Protocol Labs] + +## Authors + +- [Vasco Santos], [Protocol Labs] + +## Abstract + +A Space can be defined as a namespace for stored content. It is created locally, offline, and associated with a cryptographic key pair (identified by the did:key of the public key). Afterwards, a space MAY be registered with a web3.storage [account](./w3-account.md) and [providers](./w3-provider.md) MAY be added to the space. + +- [Capabilities](#capabilities) + - [`space/info`](#spaceinfo) + +## Language + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119](https://datatracker.ietf.org/doc/html/rfc2119). + +## Capabilities + +### `space/info` + +Get information about a given space, such as registered providers. + +> `did:key:zAliceAgent` invokes `space/info` capability provided by `did:web:web3.storage` + +```json +{ + "iss": "did:key:zAliceAgent", + "aud": "did:web:web3.storage", + "att": [ + { + "with": "did:key:zAlice", + "can": "space/info" + } + ], + "prf": [], + "sig": "..." +} +``` + +#### Space Info Failure + +```json +{ + "ran": "bafy...spaceInfo", + "out": { + "error": { + "name": "SpaceUnknown" + } + } +} +``` + +#### Space Info Success + +```json +{ + "ran": "bafy...spaceInfo", + "out": { + "ok": { + "did": "did:key:zAlice", + "providers": [ + "did:web:free.web3.storage" + ] + } + } +} +``` + +[Protocol Labs]: https://protocol.ai/ +[Vasco Santos]: https://github.com/vasco-santos