Skip to content
This repository was archived by the owner on Jan 8, 2026. It is now read-only.

Commit 23eea5a

Browse files
hannahhowardhannahhoward
committed
feat(graphsync): cleanup schema
1 parent 7313610 commit 23eea5a

2 files changed

Lines changed: 64 additions & 79 deletions

File tree

‎block-layer/graphsync/graphsync.md‎

Lines changed: 62 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -64,88 +64,69 @@ type GraphSyncNet interface {
6464
Graphsync network messages are encoded in DAG-CBOR. They have the following schema
6565

6666
```ipldsch
67-
type GraphSyncExtensions {string:Any}
67+
type GraphSyncExtensions {String:Any}
6868
type GraphSyncRequestID int
6969
type GraphSyncPriority int
7070
7171
type GraphSyncMetadatum struct {
72-
Link &Any
73-
BlockPresent bool
74-
}
72+
link &Any
73+
blockPresent Bool
74+
} representation tuple
75+
7576
type GraphSyncMetadata [GraphsyncMetadatum]
7677
7778
type GraphSyncResponseCode enum {
78-
# RequestAcknowledged means the request was received and is being worked on.
79-
| RequestAcknowledged ("10")
80-
# AdditionalPeers means additional peers were found that may be able
81-
# to satisfy the request and contained in the extra block of the response.
82-
| AdditionalPeers ("11")
83-
# NotEnoughGas means fulfilling this request requires payment.
84-
| NotEnoughGas ("12")
85-
# OtherProtocol means a different type of response than GraphSync is
86-
# contained in extra.
87-
| OtherProtocol ("13")
88-
# PartialResponse may include blocks and metadata about the in progress response
89-
# in extra.
90-
| PartialResponse ("14")
91-
# RequestPaused indicates a request is paused and will not send any more data
92-
# until unpaused
93-
| RequestPaused ("15")
94-
95-
# Success Response Codes (request terminated)
96-
97-
# RequestCompletedFull means the entire fulfillment of the GraphSync request
98-
# was sent back.
99-
| RequestCompletedFull ("20")
100-
# RequestCompletedPartial means the response is completed, and part of the
101-
# GraphSync request was sent back, but not the complete request.
102-
| RequestCompletedPartial ("21")
103-
104-
# Error Response Codes (request terminated)
105-
106-
# RequestRejected means the node did not accept the incoming request.
107-
| RequestRejected ("30")
108-
# RequestFailedBusy means the node is too busy, try again later. Backoff may
109-
# be contained in extra.
110-
| RequestFailedBusy ("31")
111-
# RequestFailedUnknown means the request failed for an unspecified reason. May
112-
# contain data about why in extra.
113-
| RequestFailedUnknown ("32")
114-
# RequestFailedLegal means the request failed for legal reasons.
115-
| RequestFailedLegal ("33")
116-
# RequestFailedContentNotFound means the respondent does not have the content.
117-
| RequestFailedContentNotFound ("34")
118-
# RequestCancelled means the responder was processing the request but decided to top, for whatever reason
119-
| RequestCancelled ("35")
79+
# Informational Codes (request in progress)
80+
81+
| RequestAcknowledged ("10")
82+
| AdditionalPeers ("11")
83+
| NotEnoughGas ("12")
84+
| OtherProtocol ("13")
85+
| PartialResponse ("14")
86+
| RequestPaused ("15")
87+
88+
# Success Response Codes (request terminated)
89+
90+
| RequestCompletedFull ("20")
91+
| RequestCompletedPartial ("21")
92+
93+
# Error Response Codes (request terminated)
94+
95+
| RequestRejected ("30")
96+
| RequestFailedBusy ("31")
97+
| RequestFailedUnknown ("32")
98+
| RequestFailedLegal ("33")
99+
| RequestFailedContentNotFound ("34")
100+
| RequestCancelled ("35")
120101
} representation int
121102
122103
type GraphSyncRequest struct {
123-
Id GraphSyncRequestID # unique id set on the requester side
124-
Root &Any # a CID for the root node in the query
125-
Selector Selector # see https://github.com/ipld/specs/blob/master/selectors/selectors.md
126-
Extensions GraphSyncExtensions # side channel information
127-
Priority GraphsyncPriority # the priority (normalized). default to 1
128-
Cancel bool # whether this cancels a request
129-
Update bool # whether this is an update to an in progress request
130-
}
104+
id GraphSyncRequestID (rename "ID") # unique id set on the requester side
105+
root &Any (rename "Root") # a CID for the root node in the query
106+
selector Selector (rename "Sel") # see https://github.com/ipld/specs/blob/master/selectors/selectors.md
107+
extensions GraphSyncExtensions (rename "Ext") # side channel information
108+
priority GraphsyncPriority (rename "Pri") # the priority (normalized). default to 1
109+
cancel Bool (rename "Canc") # whether this cancels a request
110+
update Bool (rename "Updt") # whether this is an update to an in progress request
111+
} representation map
131112
132113
type GraphSyncResponse struct {
133-
ID GraphSyncRequestID # the request id we are responding to
134-
Status GraphSyncResponseStatusCode # a status code.
135-
Metadata GraphSyncMetadata # metadata about response
136-
Extensions GraphSyncExtensions # side channel information
137-
}
114+
id GraphSyncRequestID (rename "ID") # the request id we are responding to
115+
status GraphSyncResponseStatusCode (rename "Stat") # a status code.
116+
metadata GraphSyncMetadata (rename "Meta") # metadata about response
117+
extensions GraphSyncExtensions (rename "Ext") # side channel information
118+
} representation map
138119
139120
type GraphSyncBlock struct {
140-
Prefix bytes # CID prefix (cid version, multicodec and multihash prefix (type + length)
141-
Data bytes
142-
}
121+
prefix Bytes (rename "Pre") # CID prefix (cid version, multicodec and multihash prefix (type + length)
122+
data Bytes (rename "Data")
123+
} representation map
143124
144125
type GraphSyncMessage struct {
145-
Requests [GraphSyncRequest]
146-
Responses [GraphSyncResponse]
147-
Blocks [GraphSyncBlock]
148-
}
126+
requests [GraphSyncRequest] (rename "Reqs")
127+
responses [GraphSyncResponse] (rename "Rsps")
128+
blocks [GraphSyncBlock] (rename "Blks")
129+
} representation map
149130
```
150131

151132
### Legacy Protocol Version 1.0.0
@@ -204,23 +185,25 @@ The update mechanism in conjunction with the paused response code can also be us
204185

205186
```
206187
# info - partial
207-
10 Request Acknowledged. Working on it.
208-
11 Additional Peers. PeerIDs in extra.
209-
12 Not enough vespene gas ($)
210-
13 Other Protocol - info in extra.
211-
14 Partial Response w/ metadata, may include blocks
212-
15 Request Paused, pending update, see extensions for info
188+
10 Request acknowledged, indicates request was received and is being worked on
189+
11 Additional peers, indicates additional peers were found that may be able to satisfy the request and contained in the extensions block of the response
190+
12 Not enough gas, fulfilling this request requires payment
191+
13 Other protocol, indicates a different type of response than GraphSync is contained in extensions
192+
14 Partial response, includes blocks and metadata about the in progress response
193+
15 Request paused, indicates a request is paused and will not send any more data until unpaused
213194
214195
# success - terminal
215-
20 Request Completed, full content.
216-
21 Request Completed, partial content.
196+
197+
20 Request completed, entire fulfillment of the GraphSync request was sent back.
198+
21 Request completed, partial fulfillment of the GraphSync request was sent back, but not the complete request.
217199
218200
# error - terminal
219-
30 Request Rejected. NOT working on it.
220-
31 Request failed, busy, try again later (getting dosed. backoff in extra).
221-
32 Request failed, for unknown reason. Extra may have more info.
222-
33 Request failed, for legal reasons.
223-
34 Request failed, content not found.
201+
30 Request rejected, indicates the node did not accept the incoming request.
202+
31 Request failed, indiciates the node is too busy, try again later. Backoff may be contained in extensions.
203+
32 Request failed for unknown reasons, may contain data about why in extensions.
204+
33 Request failed for legal reasons.
205+
34 Request failed because respondent does not have the content.
206+
35 Request cancelled, indicates the responder was processing the request but decided to stop. Extensions may contain information about reason for cancellation
224207
```
225208

226209
## Example Use Cases

‎block-layer/graphsync/known_extensions.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,8 @@ The responder node will execute the selector query as it would normally. However
2525

2626
### Response Metadata
2727

28+
***Legacy Graphsync Protocol 1.0.0 Only***
29+
2830
Extension Name: `graphsync/response-metadata`
2931

3032
What it does:

0 commit comments

Comments
 (0)