diff --git a/w3-aggregation.md b/w3-aggregation.md index 2c45740..6de03b8 100644 --- a/w3-aggregation.md +++ b/w3-aggregation.md @@ -117,31 +117,7 @@ In this document, we will be looking at `spade-proxy.web3.storage` as an impleme ### `aggregate/offer` -A Storefront principal can invoke a capabilty to offer an aggregate that is ready to be included in Filecoin deal(s). - -```iplsch -type AggregateOffer struct { - with StorefrontDID - nb AggregateOfferDetail -} - -type AggregateOfferDetail struct { - offer OfferCBOR - commitmentProof Proof -} - -type OfferCBOR any -type Proof any - -type struct OfferDetails { - size Int - link Link - src [URL] - commitmentProof Proof -} - -type Offer [OfferDetails] -``` +A Storefront principal can invoke a capabilty to offer an aggregate that is ready to be included in Filecoin deal(s). See [schema](#aggregateoffer-schema). > `did:web:web3.storage` invokes capability from `did:web:spade.storage` @@ -153,8 +129,11 @@ type Offer [OfferDetails] "with": "did:web:web3.storage", "can": "aggregate/offer", "nb": { - "offer": { "/": "bafy...many-cars" }, /* dag-cbor CID */ - "commitmentProof": { "/": "commitment...cars-proof" } /* commitment proof */ + "offer": { "/": "bafy...many-cars" }, /* dag-cbor CID with offer content */ + "piece": { + "link": { "/": "commitment...aggregate-proof" }, + "size": 10102020203013342343 + } /* commitment proof for aggregate */ } }], "prf": [], @@ -165,13 +144,11 @@ type Offer [OfferDetails] Invoking `aggregate/offer` capability submits an aggregate to a broker service for inclusion in one or more Filecoin deals. The `nb.offer` field represents a "Ferry" aggregate offer that is ready for a Filecoin deal. Its value is the DAG-CBOR CID that refers to a "Ferry" offer. It encodes a dag-cbor block with an array of entries representing all the CAR files to include in the aggregated deal. This block MUST be included in the CAR file that transports the invocation. Its format is: ```json -/* offers block as OfferDetails type, encoded as DAG-JSON (for readability) */ +/* offers block as PieceInfo type, encoded as DAG-JSON (for readability) */ [ { - "link": { "/": "bag...file0" }, /* CAR CID */ + "link": { "/": "commitment...car0" }, /* COMMP CID */ "size": 110101, - "commitmentProof": { "/": "commitment...car0" }, /* COMMP CID */ - "src": ["https://w3s.link/ipfs/bag...file0"] }, { /* ... */ @@ -179,7 +156,7 @@ Invoking `aggregate/offer` capability submits an aggregate to a broker service f ] ``` -Each entry of the decoded offers block, has all the necessary information for a Storage Provider to fetch and store a CAR file. The `link` field has the CAR CID, while the `commitmentProof` field has the required `proof` bytes by Storage Providers (for example, `commP`). The `size` field MUST be set to the byte size of the CAR file. The `src` field of each piece MUST be set to a (alphabetically sorted) list of URLs from which it can be fetched. Note that `src` field is optional and can be provided in a different part of the flow such as when deal is signed or through a previously agreed API. +Each entry of the decoded offers block, has all the necessary information for a Storage Provider to fetch and store a CAR file. It includes an array of Filecoin `piece` info required by Storage Providers. Out of band, Storefront will provide to Storage Providers a `src` HTTP URL to each CAR file in the offer. Broker MUST issue a signed receipt to acknowledge the received request. Issued receipt MUST contain an [effect](https://github.com/ucan-wg/invocation/#7-effect) with a subsequent task (`.fx.join` field) that is run when submitted aggregate is processed and either succeeds (implying that aggregate was accepted and deals will be arranged) or fail (with `error` describing a problem with the aggregate). @@ -204,7 +181,7 @@ See [`offer/arrange`](#offerarrange) section to see the subsequent task. ### `aggregate/get` -A Storefront principal can invoke a capability to get state of a previously accepted offer. +A Storefront principal can query state of accepted aggregate by invoking `aggregate/get` capability. See [schema](#aggregateget-schema). > `did:web:web3.storage` invokes capability from `did:web:spade.storage` @@ -216,7 +193,7 @@ A Storefront principal can invoke a capability to get state of a previously acce "with": "did:web:web3.storage", "can": "aggregate/get", "nb": { - "commitmentProof": { "/": "commitment...cars-proof" } /* commitment proof */ + "subject": { "/": "commitment...aggregate-proof" } /* commitment proof */ } }], "prf": [], @@ -257,7 +234,7 @@ Once this invocation is executed, a receipt is generated with the resulting aggr ### `offer/arrange` -When a broker receives an `aggregate/offer` invocation from a Storefront Principal, an [Effect](https://github.com/ucan-wg/invocation/#7-effect) for this submission is created with join task to be performed asynchronously. +When a broker receives an `aggregate/offer` invocation from a Storefront Principal, an [Effect](https://github.com/ucan-wg/invocation/#7-effect) for this submission is created with join task to be performed asynchronously. See [schema](#offerarrange-schema). ```json { @@ -267,7 +244,7 @@ When a broker receives an `aggregate/offer` invocation from a Storefront Princip "with": "did:web:spade.storage", "can": "offer/arrange", "nb": { - "commitmentProof": { "/": "commitment...cars-proof" } /* commitment proof */ + "pieceLink": { "/": "commitment...aggregate-proof" } /* commitment proof */ } }], "prf": [], @@ -282,7 +259,7 @@ Once this invocation is executed, a receipt is generated with the result of the "ran": "bafy...arrange", "out": { "ok": { - "commitmentProof": { "/": "commitment...cars-proof" } /* commitment proof */ + "pieceLink": { "/": "commitment...aggregate-proof" } /* commitment proof */ } }, "fx": { @@ -294,16 +271,16 @@ Once this invocation is executed, a receipt is generated with the result of the } ``` -If offered aggregate is invalid, details on failing commitmentProofs are also reported: +If offered aggregate is invalid, details on failing pieces are also reported: ```json { "ran": "bafy...invocation", "out": { "error": { - "commitmentProof": { "/": "commitment...cars-proof" } /* commitment proof */ + "pieceLink": { "/": "commitment...aggregate-proof" }, /* commitment proof */ "cause": [{ - "commitmentProof": { "/": "commitment...car0" }, + "piece": { "/": "commitment...car0" }, "reason": "reasonCode", }], }, @@ -317,15 +294,11 @@ If offered aggregate is invalid, details on failing commitmentProofs are also re } ``` -### Schema +## Schema -```ipldsch -type Aggregate union { - | Link "queued" - | Link "status" - | Link "rejected" -} representation keyed +### Base types +```ipldsch type AggregateCapability enum { AggregateOffer "aggregate/offer" AggregateGet "aggregate/get" @@ -333,57 +306,67 @@ type AggregateCapability enum { discriminantKey "can" } -type AggregateGet struct { - with StorefrontDID - nb SucceedAggregateRef +type OfferCapability union { + OfferArrange "offer/arrange" +} representation inline { + discriminantKey "can" } -type SucceedAggregateRef struct { - commitmentProof Proof +type AggregateRef struct { + pieceLink Link } -type AggregateRef struct { - commitmentProof Proof +type SubjectRef struct { + subject Link } +type StorefrontDID string +type URL string + +type BrokerDID string +``` + +### `aggregate/offer` schema + +```ipldsch type AggregateOffer struct { with StorefrontDID nb AggregateOfferDetail } type AggregateOfferDetail struct { - offer OfferCBOR - commitmentProof Proof + # Contains each individual piece within Aggregate piece + offer &Offer + # Piece as Aggregate of CARs with padding + piece PieceInfo } -type OfferCBOR any -type Proof any +type Offer [PieceInfo] -type struct OfferDetails { - size Int - link Link - src? [URL] - commitmentProof Proof +# https://github.com/filecoin-project/go-state-types/blob/1e6cf0d47cdda75383ef036fc2725d1cf51dbde8/abi/piece.go#L47-L50 +type PieceInfo { + # Size in nodes. For BLS12-381 (capacity 254 bits), must be >= 16. (16 * 8 = 128) + size Int + link Link } +``` -type Offer [OfferDetails] - -type StorefrontDID string -type URL string -type OfferCBOR any -type Proof any +### `aggregate/get` schema -type OfferCapability union { - OfferArrange "offer/arrange" -} representation inline { - discriminantKey "can" +```ipldsch +type AggregateGet struct { + with StorefrontDID + nb SubjectRef } +``` + +### `offer/arrange` schema +```ipldsch type OfferArrange struct { - with BrokerDID nb AggregateRef + with BrokerDID + nb AggregateRef } - -type BrokerDID string ``` [`did:web`]: https://w3c-ccg.github.io/did-method-web/