diff --git a/w3-aggregation.md b/w3-aggregation.md index 984da18..8b0ac52 100644 --- a/w3-aggregation.md +++ b/w3-aggregation.md @@ -130,10 +130,11 @@ A Storefront principal can invoke a capabilty to offer an aggregate that is read "can": "aggregate/offer", "nb": { "offer": { "/": "bafy...many-cars" }, /* dag-cbor CID with offer content */ - "piece": { - "link": { "/": "commitment...aggregate-proof" }, - "height": 4 /* height of the perfect binary tree for the aggregate */ - } /* commitment proof for aggregate */ + "piece": { "/": "commitment...aggregate-proof" }, /* commitment proof for aggregate */ + "deal": { + "client": "f1....wq", + "label": "deal-label" + } } }], "prf": [], @@ -141,20 +142,18 @@ A Storefront principal can invoke a capabilty to offer an aggregate that is read } ``` -Invoking `aggregate/offer` capability submits an aggregate to a broker service for inclusion in one or more Filecoin deals. The `nb.piece` field represents the proof of the `piece` to be offered for the deal. It contains the proof CID `piece.link` together with the `piece.height` of the perfect binary tree computed for this aggregate. The `height` can be used to derive the leaf count (`2 ** height`), which can then be used to derive the `size` of the piece (`leafCount * Node.Size` where `Node.Size` is 32). +Invoking `aggregate/offer` capability submits an aggregate to a broker service for inclusion in one or more Filecoin deals. + +The `nb.piece` field represents the proof of the `piece` to be offered for the deal. It is a CID with its piece size encoded. In addition, a Filecoin `nb.deal` contains the necessary fields for a Filecoin Deal proposal. More specifically, it MUST include signer wallet address `nb.deal.wallet` and MAY include an arbitrary `nb.deal.label` chosen by the client. -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 pieces to include in the aggregated deal. This array MUST be sorted in the exact same order as they were used to compute the aggregate piece CID. This block MUST be included in the CAR file that transports the invocation. Its format is: +Finally, 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 pieces to include in the aggregated deal. This array MUST be sorted in the exact same order as they were used to compute the aggregate piece CID. This block MUST be included in the CAR file that transports the invocation. Its format is: ```json -/* offers block as an adapted PieceInfo type (with tree `height` instead of `size`), encoded as DAG-JSON (for readability) */ +/* offers block as an array of piece CIDs, encoded as DAG-JSON (for readability) */ [ - { - "link": { "/": "commitment...car0" }, /* COMMP CID */ - "height": 110101, /* height of the perfect binary tree for the piece */ - }, - { - /* ... */ - } + { "/": "commitment...car0" }, /* COMMP CID */ + { "/": "commitment...car1" }, /* COMMP CID */ + /* ... */ ] ``` @@ -195,7 +194,7 @@ A Storefront principal can query state of accepted aggregate by invoking `aggreg "with": "did:web:web3.storage", "can": "aggregate/get", "nb": { - "subject": { "/": "commitment...aggregate-proof" } /* commitment proof */ + "piece": { "/": "commitment...aggregate-proof" } /* commitment proof */ } }], "prf": [], @@ -246,7 +245,7 @@ When a broker receives an `aggregate/offer` invocation from a Storefront Princip "with": "did:web:spade.storage", "can": "offer/arrange", "nb": { - "pieceLink": { "/": "commitment...aggregate-proof" } /* commitment proof */ + "piece": { "/": "commitment...aggregate-proof" } /* commitment proof */ } }], "prf": [], @@ -261,7 +260,7 @@ Once this invocation is executed, a receipt is generated with the result of the "ran": "bafy...arrange", "out": { "ok": { - "pieceLink": { "/": "commitment...aggregate-proof" } /* commitment proof */ + "piece": { "/": "commitment...aggregate-proof" } /* commitment proof */ } }, "fx": { @@ -280,7 +279,7 @@ If offered aggregate is invalid, details on failing pieces are also reported: "ran": "bafy...invocation", "out": { "error": { - "pieceLink": { "/": "commitment...aggregate-proof" }, /* commitment proof */ + "piece": { "/": "commitment...aggregate-proof" }, /* commitment proof */ "cause": [{ "piece": { "/": "commitment...car0" }, "reason": "reasonCode", @@ -314,18 +313,15 @@ type OfferCapability union { discriminantKey "can" } -type AggregateRef struct { - pieceLink Link -} - -type SubjectRef struct { - subject Link +type PieceRef struct { + piece PieceCid } type StorefrontDID string type URL string - type BrokerDID string +# from a fr32-sha2-256-trunc254-padded-binary-tree multihash +type PieceCid Link ``` ### `aggregate/offer` schema @@ -340,20 +336,22 @@ type AggregateOfferDetail struct { # Contains each individual piece within Aggregate piece offer &Offer # Piece as Aggregate of CARs with padding - piece PieceInfo + piece PieceCid + # Fields to create a contract with a Storage Provider for aggregate + deal DealProposal } -type Offer [PieceInfo] +type Offer [PieceCid] -# Adapted from `PieceInfo` type in filecoin -# https://github.com/filecoin-project/go-state-types/blob/1e6cf0d47cdda75383ef036fc2725d1cf51dbde8/abi/piece.go#L47-L50 -# Uses `height` field instead of `size`. `height` field can be used to derive `leafCount` and consequently `size`, while -# allowing the usage of smaller numbers instead of `bigint`. -type PieceInfo { - # Height of the perfect binary tree for the piece - height Int - link Link +# @see https://github.com/filecoin-project/go-state-types/blob/ff2ed169ff566458f2acd8b135d62e8ca27e7d0c/builtin/v9/market/deal.go#L201-L221 +# A subset of the deal proposal items required by broker to facilitate the contract to be created +type DealProposal struct { + # Signer wallet (f0) address + client Address + # Label is an arbitrary client chosen label to apply to the deal + label DealLabel } + ``` ### `aggregate/get` schema @@ -361,7 +359,7 @@ type PieceInfo { ```ipldsch type AggregateGet struct { with StorefrontDID - nb SubjectRef + nb PieceRef } ``` @@ -370,7 +368,7 @@ type AggregateGet struct { ```ipldsch type OfferArrange struct { with BrokerDID - nb AggregateRef + nb PieceRef } ```