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.

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

rename BlockSync to ChainExchange #1204

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 1 commit
Commits
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
101 changes: 0 additions & 101 deletions content/algorithms/block_sync.md

This file was deleted.

116 changes: 116 additions & 0 deletions content/algorithms/chain_exchange.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,116 @@
---
title: "ChainExchange"
weight: 5
dashboardWeight: 1
dashboardState: stable
dashboardAudit: missing
dashboardTests: 0
---

# ChainExchange

{{< hint info >}}
**Name**: Chain Exchange
**Protocol ID**: `/fil/chain/xchg/0.0.1`
{{< /hint >}}

ChainExchange is a simple request/response protocol that allows Filecoin nodes to request ranges of Tipsets and/or Messages from each other.
schomatis marked this conversation as resolved.
Show resolved Hide resolved

The `Request` message requests a chain segment of a given length by the hash of the highest Tipset in the segment (not necessarily heaviest Tipset of the current chain). For example, if the current height is at 5000, but a node is missing Tipsets between 4500-4700, then the `Request.Head` requested is 4700 and `Request.Length` is 200.

The `Options` allow the requester to specify whether they want to receive block headers of the Tipsets only, the transaction messages included in every block, or both.

The `Response` contains the requested chain segment in reverse iteration order. Each item in the `Chain` array contains either the block headers for that Tipset if the `Blocks` option bit in the request is set, or the messages across all blocks in that Tipset, if the `Messages` bit is set, or both, if both option bits are set.

Each `CompactedMessages` structure contains the BLS and `secp256k1` messages for the corresponding Tipset in unified arrays that encode each message once regardless of how many times it appears in the Tipset's blocks (to reduce the `Response` size). The mapping between message and the blocks into which they are included is encoded in the `BlsIncludes` and `SecpkIncludes` arrays. These arrays are indexed by the block index in the Tipset and contain in that position an array of message indexes that belong to that block. The messages themselves are in the `Bls` and `Secpk` arrays.

If not all Tipsets requested could be fetched, but the `Head` of the chain segment requested was successfully fetched (and potentially more contiguous Tipsets), then this is not considered an error and a `Partial` response code is returned. The node can continue extending the chain from the partial returned segment onwards.

```go
type Request struct {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you can embed this struct directly from the code https://github.com/filecoin-project/lotus/blob/master/chain/exchange/protocol.go#L48-L60 using https://github.com/filecoin-project/specs#embed

Example:

{{<embed src="https://github.com/filecoin-project/lotus/blob/master/chain/exchange/protocol.go" lang="go" symbol="Request" title="Exchange Protocol Request">}}

This way its easier to keep in sync.

## Head of the requested segment (block CIDs comprising the entire Tipset)
Head [Cid]
## Length of the requested segment
Length UInt
## Query options
Options UInt
}
```

```go
type Options enum {
# Include block headers
| Headers 1
# Include block messages
| Messages 2
}

type Response struct {
## Response Status
Status status
## Optional error message
ErrorMessage string
## Returned segment containing block messages and/or headers
Chain []*BSTipSet
yiannisbot marked this conversation as resolved.
Show resolved Hide resolved
}

type Status enum {
## Success: the entire segment requested was fetched.
| Ok 0
## We could not fetch all Tipsets requested but at least we returned
## the `Head` requested (and potentially more contiguous Tipsets).
## Not considered an error.
| Partial 101
## `Request.Head` not found.
| NotFound 201
## Requester is making too many requests.
| GoAway 202
## Internal error occurred.
| InternalError 203
## Request was badly formed.
| BadRequest 204
}

type CompactedMessages struct {
## Array of BLS messages in this tipset.
Bls [Message]
## Array of messages indexes present in each block:
## `BlsIncludes[BI] -> [MI]`
## * BI: block index in the tipset.
## * MI: message index in `Bls` list.
BlsIncludes [[Uint]]

## Array of `secp256k1` messages.
Secpk [SignedMessage]
## Inclusion array, see `BlsIncludes`.
SecpkIncludes [[UInt]]
}
```

## Example

For the set of arrays in the following `BSTipSet`, the corresponding messages per block are as shown below:

**BSTipSet**
```js
Blocks: [b0, b1]
CompactedMessages
```

**CompactedMessages**
```js
Secpk: [mA, mB, mC, mD]
SecpkIncludes: [[0, 1, 3], [1, 2, 0]]
```

**Messages corresponding to each Block**
```js
Block 'b0': [mA, mB, mD]
Block 'b1': [mB, mC, mA]
```

In other words, the first element of the `SecpkIncludes` array: `[0, 1, 3]` points to the 1st, 2nd and 4th element of the `Secpk` array: `mA, mB, mD`, which correspond to the 1st element of the `Blocks` array `b0`. Hence, `Block 'b0': [mA, mB, mD]`.

Similarly, the second element of the `SecpkIncludes` array: `[1, 2, 0]` points to the 2nd, 3rd and 1st element of the `Secpk` array: `mB, mC, mA`, which correspond to the 2nd element of the `Blocks` array `b1`. Hence, `Block 'b1': [mB, mC, mA]`.

See [Lotus](https://github.com/filecoin-project/lotus/tree/master/chain/exchange) for an example implementation of the protocol.