Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

fix: aggregate spec offer complete #70

Closed
wants to merge 2 commits into from
Closed

fix: aggregate spec offer complete #70

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a88291e
fix: aggregate spec can rely on piece cid with encoded size (#68)
vasco-santos Jul 24, 2023
f2cdd56
fix: aggregate spec offer complete
vasco-santos Jul 24, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 35 additions & 37 deletions w3-aggregation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -130,31 +130,30 @@ 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": [],
"sig": "..."
}
```

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 */
/* ... */
]
```

Expand Down Expand Up @@ -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": [],
Expand Down Expand Up @@ -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": [],
Expand All @@ -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": {
Expand All @@ -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",
Expand Down Expand Up @@ -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
Expand All @@ -340,28 +336,30 @@ 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

```ipldsch
type AggregateGet struct {
with StorefrontDID
nb SubjectRef
nb PieceRef
}
```

Expand All @@ -370,7 +368,7 @@ type AggregateGet struct {
```ipldsch
type OfferArrange struct {
with BrokerDID
nb AggregateRef
nb PieceRef
}
```

Expand Down