From 7a58df88e2c751c4d9b411e97194c1f7810ee95b Mon Sep 17 00:00:00 2001 From: Vasco Santos Date: Thu, 1 Feb 2024 13:45:19 +0100 Subject: [PATCH 1/3] feat: w3compute protocol --- w3-compute.md | 125 +++++++++++++++++++++++++++++++++++++++++++++++++ w3-filecoin.md | 3 +- 2 files changed, 127 insertions(+), 1 deletion(-) create mode 100644 w3-compute.md diff --git a/w3-compute.md b/w3-compute.md new file mode 100644 index 00000000..1d4ade01 --- /dev/null +++ b/w3-compute.md @@ -0,0 +1,125 @@ +# W3 Compute Protocol + +![status:draft](https://img.shields.io/badge/status-reliable-green.svg?style=flat-square) + +## Editors + +- [Vasco Santos], [Protocol Labs] + +## Authors + +- [Vasco Santos], [Protocol Labs] + +# Abstract + +This spec describes a [UCAN] protocol allowing an implementer to perform simple computations over data on behalf of an issuer. + +## 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). + +# Table of Contents + +- [Introduction](#introduction) +- [Capabilities](#capabilities) + - [`compute/` namespace](#comput-namespace) + - [`compute/*`](#compute) + - [`compute/piececid`](#computepiececid) +- [Schema](#schema) + - [`compute/piececid` schema](#computepiececid-schema) + +# Introduction + +Within the w3up protocol flows, some computations MUST be performed over data. These case range from computing proofs to data indexes, as well as to verify client side offered computations. + +The `w3-compute` protocol aims to enable clients to hire compute services to delegate some work, as well as for `w3-up` platform to hire third party compute services to verify client side offered computations if desirable. + +Note that the discovery process by actors looking for services providing given computations is for now out of scope of this spec. + +# Capabilities + +### `compute/` namespace + +The `compute/` namespace contains capabilities relating to computations. + +### `compute/*` + +> Delegate all capabilities in the `compute/` namespace + +The `compute/*` capability is the "top" capability of the `compute/*` namespace. `compute/*` can be delegated to a user agent, but cannot be invoked directly. Instead, it allows the agent to derive any capability in the `compute/` namespace, provided the resource URI matches the one in the `compute/*` capability delegation. + +In other words, if an agent has a delegation for `compute/*` for a given space URI, they can invoke any capability in the `compute/` namespace using that space as the resource. + +### `compute/piececid` + +> Request computation of a PieceCIDv2 per [FRC-0069](https://github.com/filecoin-project/FIPs/blob/master/FRCs/frc-0069.md). A CID representation for the FR32 padded sha256-trunc254-padded binary merkle trees used in Filecoin Piece Commitments. + +> `did:key:zAliceAgent` invokes `compute/piececid` capability provided by `did:web:web3.storage` + +```json +{ + "iss": "did:key:zAliceAgent", + "aud": "did:web:web3.storage", + "att": [ + { + "with": "did:key:zAliceAgent", + "can": "compute/piececid", + "nb": { + /* CID of the uploaded content */ + "content": { "/": "bag...car" } + } + } + ], + "prf": [], + "sig": "..." +} +``` + +##### Compute PieceCID Failure + +The service MAY fail the invocation if the linked `content` is not found. Implementer can rely on IPFS gateways, location claims or any other service to try to find the CAR bytes. + +```json +{ + "ran": "bafy...computePiececid", + "out": { + "error": { + "name": "ContentNotFoundError", + "content": { "/": "bag...car" } + } + } +} +``` + +##### Compute PieceCID Success + +```json +{ + "ran": "bafy...filAccept", + "out": { + "ok": { + /* commitment proof for piece */ + "piece": { "/": "commitment...car" } + } + } +} +``` + +## Schema + +### `compute/piececid` schema + +```ipldsch +type ComputePieceCid struct { + with AgentDID + nb ComputePieceCidDetail +} + +type ComputePieceCidDetail struct { + # CID of file previously added to IPFS Network + content &Content +} +``` + +[Protocol Labs]: https://protocol.ai/ +[Vasco Santos]: https://github.com/vasco-santos diff --git a/w3-filecoin.md b/w3-filecoin.md index e54cd266..e3e229a6 100644 --- a/w3-filecoin.md +++ b/w3-filecoin.md @@ -310,7 +310,8 @@ This task is effectively a shortcut allowing an observer to find out the result #### `filecoin/submit` -The task MUST be invoked by the [Storefront] which MAY be used to verify the offered content piece before propagating it through the pipeline. +The task MUST be invoked by the [Storefront] which MAY be used to verify the offered content piece before propagating it through the pipeline. For this, [Storefront] may ask a third party service to [compute](./w3-compute.md) the PieceCID for validation. + > `did:web:web3.storage` invokes capability from `did:web:web3.storage` ```json From b454b104cfe81d78cc7b37faef552509527fddda Mon Sep 17 00:00:00 2001 From: Vasco Santos Date: Thu, 1 Feb 2024 13:53:34 +0100 Subject: [PATCH 2/3] chore: add words to ignore checking --- .github/workflows/words-to-ignore.txt | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/workflows/words-to-ignore.txt b/.github/workflows/words-to-ignore.txt index f6cfd910..325e11e1 100644 --- a/.github/workflows/words-to-ignore.txt +++ b/.github/workflows/words-to-ignore.txt @@ -156,3 +156,7 @@ AccountA AgentA IssuerA AudiencePrincipal +PieceCID +PieceCIDv2 +FR32 +sha256-trunc254-padded From afb7916fda10bba0698ea66114c43de774e54e4d Mon Sep 17 00:00:00 2001 From: Vasco Santos Date: Thu, 1 Feb 2024 14:56:01 +0100 Subject: [PATCH 3/3] chore: appease lint --- w3-compute.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/w3-compute.md b/w3-compute.md index 1d4ade01..6a03cea2 100644 --- a/w3-compute.md +++ b/w3-compute.md @@ -22,7 +22,7 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S - [Introduction](#introduction) - [Capabilities](#capabilities) - - [`compute/` namespace](#comput-namespace) + - [`compute/` namespace](#compute-namespace) - [`compute/*`](#compute) - [`compute/piececid`](#computepiececid) - [Schema](#schema) @@ -38,11 +38,11 @@ Note that the discovery process by actors looking for services providing given c # Capabilities -### `compute/` namespace +## `compute/` namespace -The `compute/` namespace contains capabilities relating to computations. +The `compute/` namespace contains capabilities relating to computations. -### `compute/*` +## `compute/*` > Delegate all capabilities in the `compute/` namespace @@ -50,9 +50,9 @@ The `compute/*` capability is the "top" capability of the `compute/*` namespace. In other words, if an agent has a delegation for `compute/*` for a given space URI, they can invoke any capability in the `compute/` namespace using that space as the resource. -### `compute/piececid` +## `compute/piececid` -> Request computation of a PieceCIDv2 per [FRC-0069](https://github.com/filecoin-project/FIPs/blob/master/FRCs/frc-0069.md). A CID representation for the FR32 padded sha256-trunc254-padded binary merkle trees used in Filecoin Piece Commitments. +Request computation of a PieceCIDv2 per [FRC-0069](https://github.com/filecoin-project/FIPs/blob/master/FRCs/frc-0069.md). A CID representation for the FR32 padded sha256-trunc254-padded binary merkle trees used in Filecoin Piece Commitments. > `did:key:zAliceAgent` invokes `compute/piececid` capability provided by `did:web:web3.storage` @@ -75,7 +75,7 @@ In other words, if an agent has a delegation for `compute/*` for a given space U } ``` -##### Compute PieceCID Failure +### Compute PieceCID Failure The service MAY fail the invocation if the linked `content` is not found. Implementer can rely on IPFS gateways, location claims or any other service to try to find the CAR bytes. @@ -91,7 +91,7 @@ The service MAY fail the invocation if the linked `content` is not found. Implem } ``` -##### Compute PieceCID Success +### Compute PieceCID Success ```json { @@ -105,9 +105,9 @@ The service MAY fail the invocation if the linked `content` is not found. Implem } ``` -## Schema +# Schema -### `compute/piececid` schema +## `compute/piececid` schema ```ipldsch type ComputePieceCid struct {