@cancore/contracts 0.1.0 → 0.2.0-rc.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/README.md +168 -9
  2. package/dist/abi.d.ts +6086 -1675
  3. package/dist/abi.js +1 -1
  4. package/dist/chunk-NV5IUURP.js +9252 -0
  5. package/dist/chunk-NV5IUURP.js.map +1 -0
  6. package/dist/{chunk-CIBYXHSX.js → chunk-VODZRADO.js} +2 -2
  7. package/dist/chunk-VODZRADO.js.map +1 -0
  8. package/dist/index.d.ts +849 -28
  9. package/dist/index.js +2065 -16
  10. package/dist/index.js.map +1 -1
  11. package/dist/networks.d.ts +2 -2
  12. package/dist/networks.js +1 -1
  13. package/package.json +10 -8
  14. package/spec/abi/AttestorSet.json +476 -0
  15. package/spec/abi/CNRX.json +1294 -0
  16. package/spec/abi/CNRXStaking.json +510 -0
  17. package/spec/abi/CancoreRouter.json +2564 -0
  18. package/spec/abi/FeeVault.json +604 -0
  19. package/spec/abi/HTLC.json +717 -0
  20. package/spec/abi/IBurnMintERC20.json +252 -0
  21. package/spec/abi/ICancoreRouter.json +1226 -0
  22. package/spec/abi/IHTLC.json +382 -0
  23. package/spec/abi/IPermit2.json +150 -0
  24. package/spec/abi/MultiBalanceChecker.json +34 -0
  25. package/spec/abi/PointsClaim.json +791 -0
  26. package/spec/protocol/asyncapi.json +1050 -0
  27. package/spec/protocol/messages.schema.json +414 -0
  28. package/spec/protocol/records.schema.json +93 -0
  29. package/spec/protocol/rest.schema.json +115 -0
  30. package/spec/protocol/typed-data/FillerAuth.json +58 -0
  31. package/spec/protocol/typed-data/FillerQuote.json +75 -0
  32. package/spec/protocol/typed-data/GatewayMessage.json +90 -0
  33. package/spec/protocol/typed-data/StakeBinding.json +75 -0
  34. package/spec/protocol/typed-data/TicketIntent.json +65 -0
  35. package/spec/protocol/typed-data/TicketReceipt.json +51 -0
  36. package/spec/protocol/vectors/draw.json +61 -0
  37. package/spec/protocol/vectors/jcs.json +59 -0
  38. package/spec/protocol/vectors/messages.json +343 -0
  39. package/spec/protocol/vectors/records.json +81 -0
  40. package/spec/typed-data/FillProof.json +199 -0
  41. package/spec/typed-data/FillTicket.json +83 -0
  42. package/spec/typed-data/Order.json +141 -0
  43. package/spec/typed-data/Quote.json +69 -0
  44. package/spec/vectors/canton-order.json +67 -0
  45. package/dist/chunk-CIBYXHSX.js.map +0 -1
  46. package/dist/chunk-ZSX67S72.js +0 -3423
  47. package/dist/chunk-ZSX67S72.js.map +0 -1
@@ -0,0 +1,414 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://cancore.io/schemas/filler-protocol/v1/messages.schema.json",
4
+ "title": "Cancore filler protocol v1 — WebSocket frames",
5
+ "$comment": "One $def per frame type, validated by name ($defs/<type>). The schemas encode the SENDER rule (protocol §3.1): lowercase hex, uint64 and wider as canonical decimal strings, uint8/16/32 as JSON integers, gateway times in milliseconds. No object is closed (V-2): receivers ignore unknown fields, takers ignore unknown S→F types, and treat an unknown reason/result/code as OTHER/generic. Every enum is open: anyOf [known values, futureEnumValue]. x-direction: S2F = gateway to taker (signed, addressed, timed), F2S = taker to gateway, both = either way (ping/pong; <type>S2F is the signed gateway copy, <type>F2S the taker's).",
6
+ "$defs": {
7
+ "uintDec64": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "maxLength": 20, "description": "uint64 as a decimal string: digits only, no sign, no exponent, no leading zero" },
8
+ "uintDec256": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "maxLength": 78, "description": "uint256 as a decimal string" },
9
+ "intDecUsd": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "signed decimal USD amount" },
10
+ "uint8": { "type": "integer", "minimum": 0, "maximum": 255 },
11
+ "uint16": { "type": "integer", "minimum": 0, "maximum": 65535 },
12
+ "uint32": { "type": "integer", "minimum": 0, "maximum": 4294967295 },
13
+ "address": { "type": "string", "pattern": "^0x[0-9a-f]{40}$", "description": "EVM address, lowercase hex" },
14
+ "bytes32": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" },
15
+ "sig65": { "type": "string", "pattern": "^0x[0-9a-f]{128}(1b|1c)$", "description": "65-byte r ‖ s ‖ v, low-s, v ∈ {27, 28}" },
16
+ "timeMs": { "type": "integer", "minimum": 1000000000000, "maximum": 9007199254740991, "description": "unix milliseconds, gateway clock; the minimum rejects seconds" },
17
+ "durationMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
18
+ "timeS": { "$ref": "#/$defs/uintDec64", "description": "unix seconds as a decimal string (on-chain and signed times)" },
19
+ "caip2": { "type": "string", "pattern": "^(eip155:[1-9][0-9]*|canton:(mainnet|testnet|devnet))$" },
20
+ "cantonAsset": {
21
+ "type": "object",
22
+ "required": ["admin", "id"],
23
+ "properties": { "admin": { "type": "string", "minLength": 1 }, "id": { "type": "string", "minLength": 1 } }
24
+ },
25
+ "asset": { "oneOf": [{ "$ref": "#/$defs/address" }, { "$ref": "#/$defs/cantonAsset" }] },
26
+ "requestId": { "type": "string", "pattern": "^[!-~]{1,64}$", "description": "1..64 printable ASCII (Canonical.daml:90-93)" },
27
+ "fillerId": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,62}$" },
28
+ "messageId": { "type": "string", "minLength": 1, "maxLength": 64 },
29
+ "protocolVersion": { "const": "1" },
30
+ "order": {
31
+ "type": "object",
32
+ "description": "ICancoreRouter.Order, eleven fields, every numeric field a decimal string (the shape of canton-order.json vector.order)",
33
+ "required": ["user", "originChainId", "inputToken", "inputAmount", "destination", "outputAsset", "minReceived", "recipient", "createdAt", "fillDeadline", "feeBps"],
34
+ "properties": {
35
+ "user": { "$ref": "#/$defs/address" },
36
+ "originChainId": { "$ref": "#/$defs/uintDec64" },
37
+ "inputToken": { "$ref": "#/$defs/address" },
38
+ "inputAmount": { "$ref": "#/$defs/uintDec256" },
39
+ "destination": { "$ref": "#/$defs/bytes32" },
40
+ "outputAsset": { "$ref": "#/$defs/bytes32" },
41
+ "minReceived": { "$ref": "#/$defs/uintDec256" },
42
+ "recipient": { "$ref": "#/$defs/bytes32" },
43
+ "createdAt": { "$ref": "#/$defs/timeS" },
44
+ "fillDeadline": { "$ref": "#/$defs/timeS" },
45
+ "feeBps": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,3}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5])$", "description": "uint16" }
46
+ }
47
+ },
48
+ "ticket": {
49
+ "type": "object",
50
+ "required": ["orderHash", "filler", "attempt", "validFrom", "validUntil"],
51
+ "properties": {
52
+ "orderHash": { "$ref": "#/$defs/bytes32" },
53
+ "filler": { "$ref": "#/$defs/address" },
54
+ "attempt": { "$ref": "#/$defs/uint32" },
55
+ "validFrom": { "$ref": "#/$defs/timeS" },
56
+ "validUntil": { "$ref": "#/$defs/timeS" }
57
+ }
58
+ },
59
+ "futureEnumValue": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]*$", "description": "a value added to an open enum within v1 (V-2); the receiver treats it as OTHER/generic. Every protocol enum is `anyOf: [{enum: known values}, futureEnumValue]`" },
60
+ "declineReason": {
61
+ "anyOf": [
62
+ { "enum": ["NO_INVENTORY", "RISK_LIMIT", "PRICE_MOVED", "PAUSED", "OTHER", "TICKET_SIGNER_UNKNOWN", "TICKET_MISMATCH", "TICKET_TTL_TOO_SHORT", "TICKET_ISSUED_LATE", "TICKET_BEYOND_DEADLINE", "ESCROW_NOT_OPEN", "ESCROW_MISMATCH", "PROOF_WINDOW_TOO_SHORT", "SKEW_MARGIN_TOO_SHORT", "DRAW_MISMATCH"] },
63
+ { "$ref": "#/$defs/futureEnumValue" }
64
+ ]
65
+ },
66
+ "errorCode": {
67
+ "anyOf": [
68
+ { "enum": ["BAD_REQUEST", "UNAUTHENTICATED", "UNSUPPORTED_VERSION", "UNSUPPORTED_TYPE", "BAD_SIGNATURE", "UNKNOWN_REQUEST", "UNKNOWN_TICKET", "TICKET_CLOSED", "NOT_ELIGIBLE", "RATE_LIMITED", "INTERNAL"] },
69
+ { "$ref": "#/$defs/futureEnumValue" }
70
+ ]
71
+ },
72
+ "expiredResult": { "anyOf": [{ "enum": ["FILLED", "NO_SHOW", "NO_SHOW_UNCONFIRMED", "EXEMPT"] }, { "$ref": "#/$defs/futureEnumValue" }] },
73
+ "exemptReason": { "anyOf": [{ "enum": ["DESTINATION_HALTED", "GATEWAY_FAULT", "REORGED_AFTER_INCLUSION", "RECIPIENT_NOT_READY", "OTHER"] }, { "$ref": "#/$defs/futureEnumValue" }] },
74
+ "quoteAckStatus": { "anyOf": [{ "enum": ["COUNTED", "LATE", "SHORT_TTL"] }, { "$ref": "#/$defs/futureEnumValue" }], "description": "verdict at receipt time; the final status is on GET /v1/filler/quotes" },
75
+ "penaltyStep": { "anyOf": [{ "enum": ["L1", "L2", "L3", "L4"] }, { "$ref": "#/$defs/futureEnumValue" }] },
76
+ "s2fEnvelope": {
77
+ "type": "object",
78
+ "required": ["type", "sentAt", "sig"],
79
+ "properties": {
80
+ "type": { "type": "string" },
81
+ "fillerId": { "$ref": "#/$defs/fillerId", "description": "the addressee" },
82
+ "sentAt": { "$ref": "#/$defs/timeMs" },
83
+ "sig": { "$ref": "#/$defs/sig65", "description": "gateway key over GatewayMessage{bodyHash = keccak256(JCS(frame without sig))}" },
84
+ "re": { "$ref": "#/$defs/messageId" }
85
+ }
86
+ },
87
+ "s2fBase": { "allOf": [{ "$ref": "#/$defs/s2fEnvelope" }, { "type": "object", "required": ["fillerId"], "properties": { "fillerId": { "$ref": "#/$defs/fillerId" } } }] },
88
+ "f2sBase": {
89
+ "type": "object",
90
+ "required": ["type", "id"],
91
+ "properties": { "type": { "type": "string" }, "id": { "$ref": "#/$defs/messageId" } }
92
+ },
93
+ "auth.challenge": {
94
+ "x-direction": "S2F",
95
+ "type": "object",
96
+ "description": "First frame after connect; the addressee is not known yet, so no fillerId",
97
+ "allOf": [{ "$ref": "#/$defs/s2fEnvelope" }],
98
+ "required": ["type", "nonce", "expiresAt"],
99
+ "properties": { "type": { "const": "auth.challenge" }, "nonce": { "$ref": "#/$defs/bytes32" }, "expiresAt": { "$ref": "#/$defs/timeS" } }
100
+ },
101
+ "auth.response": {
102
+ "x-direction": "F2S",
103
+ "type": "object",
104
+ "description": "sig = FillerAuth{fillerId, nonce, expiresAt} by a registered quote key",
105
+ "allOf": [{ "$ref": "#/$defs/f2sBase" }],
106
+ "required": ["type", "fillerId", "keyAddress", "protocolVersion", "sig"],
107
+ "properties": {
108
+ "type": { "const": "auth.response" },
109
+ "fillerId": { "$ref": "#/$defs/fillerId" },
110
+ "keyAddress": { "$ref": "#/$defs/address" },
111
+ "protocolVersion": { "type": "string", "description": "the gateway answers UNSUPPORTED_VERSION to anything it does not serve; v1 senders send \"1\"" },
112
+ "sig": { "$ref": "#/$defs/sig65" }
113
+ }
114
+ },
115
+ "auth.ok": {
116
+ "x-direction": "S2F",
117
+ "type": "object",
118
+ "allOf": [{ "$ref": "#/$defs/s2fBase" }],
119
+ "required": ["type", "heartbeatIntervalMs"],
120
+ "properties": { "type": { "const": "auth.ok" }, "heartbeatIntervalMs": { "$ref": "#/$defs/durationMs" } }
121
+ },
122
+ "ping": {
123
+ "x-direction": "both",
124
+ "description": "Heartbeat, either way. A receiver checks the copy of its direction: pingS2F (gateway to taker: signed, addressed, timed) or pingF2S (unsigned)",
125
+ "anyOf": [{ "$ref": "#/$defs/pingF2S" }, { "$ref": "#/$defs/pingS2F" }]
126
+ },
127
+ "pingF2S": {
128
+ "type": "object",
129
+ "required": ["type", "id"],
130
+ "properties": { "type": { "const": "ping" }, "id": { "$ref": "#/$defs/messageId" } }
131
+ },
132
+ "pingS2F": {
133
+ "type": "object",
134
+ "allOf": [{ "$ref": "#/$defs/s2fBase" }],
135
+ "required": ["type", "id"],
136
+ "properties": { "type": { "const": "ping" }, "id": { "$ref": "#/$defs/messageId" } }
137
+ },
138
+ "pong": {
139
+ "x-direction": "both",
140
+ "description": "Answer to a ping, re = ping.id. A receiver checks the copy of its direction: pongS2F (signed, addressed, timed) or pongF2S (unsigned)",
141
+ "anyOf": [{ "$ref": "#/$defs/pongF2S" }, { "$ref": "#/$defs/pongS2F" }]
142
+ },
143
+ "pongF2S": {
144
+ "type": "object",
145
+ "required": ["type", "re"],
146
+ "properties": { "type": { "const": "pong" }, "re": { "$ref": "#/$defs/messageId" } }
147
+ },
148
+ "pongS2F": {
149
+ "type": "object",
150
+ "allOf": [{ "$ref": "#/$defs/s2fBase" }],
151
+ "required": ["type", "re"],
152
+ "properties": { "type": { "const": "pong" }, "re": { "$ref": "#/$defs/messageId" } }
153
+ },
154
+ "error": {
155
+ "x-direction": "S2F",
156
+ "type": "object",
157
+ "description": "Reply to the F→S frame `re`; also the REST error body. fillerId is absent before authentication",
158
+ "allOf": [{ "$ref": "#/$defs/s2fEnvelope" }],
159
+ "required": ["type", "code", "message"],
160
+ "properties": { "type": { "const": "error" }, "code": { "$ref": "#/$defs/errorCode" }, "message": { "type": "string" } }
161
+ },
162
+ "epoch.weights": {
163
+ "x-direction": "S2F",
164
+ "type": "object",
165
+ "allOf": [{ "$ref": "#/$defs/s2fBase" }],
166
+ "required": ["type", "epochId", "startsAt", "endsAt", "weightsRoot"],
167
+ "properties": {
168
+ "type": { "const": "epoch.weights" },
169
+ "epochId": { "$ref": "#/$defs/uintDec64" },
170
+ "startsAt": { "$ref": "#/$defs/timeS" },
171
+ "endsAt": { "$ref": "#/$defs/timeS" },
172
+ "weightsRoot": { "$ref": "#/$defs/bytes32" }
173
+ }
174
+ },
175
+ "quote.request": {
176
+ "x-direction": "S2F",
177
+ "type": "object",
178
+ "allOf": [{ "$ref": "#/$defs/s2fBase" }],
179
+ "required": ["type", "requestId", "route", "inputToken", "inputAmount", "outputAsset", "feeBps", "fillDeadlineHint", "windowCloseAt", "quoteTtlMs"],
180
+ "properties": {
181
+ "type": { "const": "quote.request" },
182
+ "requestId": { "$ref": "#/$defs/requestId" },
183
+ "route": {
184
+ "type": "object",
185
+ "required": ["src", "dst"],
186
+ "properties": { "src": { "$ref": "#/$defs/caip2" }, "dst": { "$ref": "#/$defs/caip2" } }
187
+ },
188
+ "inputToken": { "$ref": "#/$defs/asset" },
189
+ "inputAmount": { "$ref": "#/$defs/uintDec256", "description": "the total T the maker deposits (inclusive fee), input base units" },
190
+ "outputAsset": { "$ref": "#/$defs/asset" },
191
+ "feeBps": { "$ref": "#/$defs/uint16" },
192
+ "fillDeadlineHint": { "$ref": "#/$defs/timeS" },
193
+ "windowCloseAt": { "$ref": "#/$defs/timeMs" },
194
+ "quoteTtlMs": { "$ref": "#/$defs/durationMs" },
195
+ "imbalanceHint": {
196
+ "type": "object",
197
+ "required": ["dstAsset", "netFlow24hUsd"],
198
+ "properties": { "dstAsset": { "$ref": "#/$defs/asset" }, "netFlow24hUsd": { "$ref": "#/$defs/intDecUsd" } }
199
+ }
200
+ }
201
+ },
202
+ "quote": {
203
+ "x-direction": "F2S",
204
+ "type": "object",
205
+ "description": "sig = FillerQuote{keccak256(utf8(requestId)), filler, amountOut, validUntil, nonce} by the quote key; counts only if validUntil × 1000 ≥ windowCloseAt + quoteTtlMs",
206
+ "allOf": [{ "$ref": "#/$defs/f2sBase" }],
207
+ "required": ["type", "requestId", "filler", "amountOut", "validUntil", "nonce", "sig"],
208
+ "properties": {
209
+ "type": { "const": "quote" },
210
+ "requestId": { "$ref": "#/$defs/requestId" },
211
+ "filler": { "$ref": "#/$defs/address" },
212
+ "amountOut": { "$ref": "#/$defs/uintDec256" },
213
+ "validUntil": { "$ref": "#/$defs/timeS" },
214
+ "nonce": { "$ref": "#/$defs/uintDec64" },
215
+ "sig": { "$ref": "#/$defs/sig65" }
216
+ }
217
+ },
218
+ "quote.ack": {
219
+ "x-direction": "S2F",
220
+ "type": "object",
221
+ "description": "For every well-formed, correctly signed quote, late ones included (S-12)",
222
+ "allOf": [{ "$ref": "#/$defs/s2fBase" }],
223
+ "required": ["type", "requestId", "quoteHash", "receivedAt", "status"],
224
+ "properties": {
225
+ "type": { "const": "quote.ack" },
226
+ "requestId": { "$ref": "#/$defs/requestId" },
227
+ "quoteHash": { "$ref": "#/$defs/bytes32" },
228
+ "receivedAt": { "$ref": "#/$defs/timeMs" },
229
+ "status": { "$ref": "#/$defs/quoteAckStatus" }
230
+ }
231
+ },
232
+ "quote.reconfirm": {
233
+ "x-direction": "S2F",
234
+ "type": "object",
235
+ "allOf": [{ "$ref": "#/$defs/s2fBase" }],
236
+ "required": ["type", "orderHash", "requestId", "order", "amountOut", "ticketTtl", "replyBy"],
237
+ "properties": {
238
+ "type": { "const": "quote.reconfirm" },
239
+ "orderHash": { "$ref": "#/$defs/bytes32" },
240
+ "requestId": { "$ref": "#/$defs/requestId" },
241
+ "order": { "$ref": "#/$defs/order" },
242
+ "amountOut": { "$ref": "#/$defs/uintDec256" },
243
+ "ticketTtl": { "$ref": "#/$defs/uint32", "description": "seconds" },
244
+ "replyBy": { "$ref": "#/$defs/timeMs" }
245
+ }
246
+ },
247
+ "quote.reconfirm.reply": {
248
+ "x-direction": "F2S",
249
+ "type": "object",
250
+ "allOf": [{ "$ref": "#/$defs/f2sBase" }],
251
+ "required": ["type", "orderHash", "accept"],
252
+ "properties": {
253
+ "type": { "const": "quote.reconfirm.reply" },
254
+ "orderHash": { "$ref": "#/$defs/bytes32" },
255
+ "accept": { "type": "boolean" },
256
+ "validUntil": { "$ref": "#/$defs/timeS" },
257
+ "nonce": { "$ref": "#/$defs/uintDec64" },
258
+ "sig": { "$ref": "#/$defs/sig65" }
259
+ },
260
+ "if": { "type": "object", "properties": { "accept": { "const": true } }, "required": ["accept"] },
261
+ "then": { "type": "object", "required": ["validUntil", "nonce", "sig"], "properties": { "validUntil": true, "nonce": true, "sig": true } }
262
+ },
263
+ "ticket.offer": {
264
+ "x-direction": "S2F",
265
+ "type": "object",
266
+ "allOf": [{ "$ref": "#/$defs/s2fBase" }],
267
+ "required": ["type", "orderHash", "attempt", "order", "amountOut", "validFrom", "validUntil", "acceptBy"],
268
+ "properties": {
269
+ "type": { "const": "ticket.offer" },
270
+ "orderHash": { "$ref": "#/$defs/bytes32" },
271
+ "attempt": { "$ref": "#/$defs/uint32" },
272
+ "order": { "$ref": "#/$defs/order" },
273
+ "amountOut": { "$ref": "#/$defs/uintDec256" },
274
+ "validFrom": { "$ref": "#/$defs/timeS" },
275
+ "validUntil": { "$ref": "#/$defs/timeS" },
276
+ "acceptBy": { "$ref": "#/$defs/timeMs" }
277
+ }
278
+ },
279
+ "ticket.intent": {
280
+ "x-direction": "F2S",
281
+ "type": "object",
282
+ "description": "sig = TicketIntent{orderHash, attempt, validFrom, validUntil} by the filler address; values equal the offer",
283
+ "allOf": [{ "$ref": "#/$defs/f2sBase" }],
284
+ "required": ["type", "orderHash", "attempt", "validFrom", "validUntil", "sig"],
285
+ "properties": {
286
+ "type": { "const": "ticket.intent" },
287
+ "orderHash": { "$ref": "#/$defs/bytes32" },
288
+ "attempt": { "$ref": "#/$defs/uint32" },
289
+ "validFrom": { "$ref": "#/$defs/timeS" },
290
+ "validUntil": { "$ref": "#/$defs/timeS" },
291
+ "sig": { "$ref": "#/$defs/sig65" }
292
+ }
293
+ },
294
+ "ticket.decline": {
295
+ "x-direction": "F2S",
296
+ "type": "object",
297
+ "allOf": [{ "$ref": "#/$defs/f2sBase" }],
298
+ "required": ["type", "orderHash", "attempt", "reason"],
299
+ "properties": {
300
+ "type": { "const": "ticket.decline" },
301
+ "orderHash": { "$ref": "#/$defs/bytes32" },
302
+ "attempt": { "$ref": "#/$defs/uint32" },
303
+ "reason": { "$ref": "#/$defs/declineReason" },
304
+ "detail": { "type": "string" }
305
+ }
306
+ },
307
+ "ticket.intent.ack": {
308
+ "x-direction": "S2F",
309
+ "type": "object",
310
+ "description": "Idempotent: a repeated identical intent gets the identical ack",
311
+ "allOf": [{ "$ref": "#/$defs/s2fBase" }],
312
+ "required": ["type", "orderHash", "attempt", "intentHash", "receivedAt"],
313
+ "properties": {
314
+ "type": { "const": "ticket.intent.ack" },
315
+ "orderHash": { "$ref": "#/$defs/bytes32" },
316
+ "attempt": { "$ref": "#/$defs/uint32" },
317
+ "intentHash": { "$ref": "#/$defs/bytes32" },
318
+ "receivedAt": { "$ref": "#/$defs/timeMs" }
319
+ }
320
+ },
321
+ "ticket.issued": {
322
+ "x-direction": "S2F",
323
+ "type": "object",
324
+ "description": "form discriminates the EVM-destination ticket (FillTicket + ticketSig) from the Canton-destination one (DeliveryOrder); a form added within v1 (V-2) is checked against the common fields only",
325
+ "required": ["type", "form", "orderHash", "attempt"],
326
+ "properties": {
327
+ "type": { "const": "ticket.issued" },
328
+ "form": { "anyOf": [{ "enum": ["evm", "canton"] }, { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" }] },
329
+ "orderHash": { "$ref": "#/$defs/bytes32" },
330
+ "attempt": { "$ref": "#/$defs/uint32" }
331
+ },
332
+ "allOf": [
333
+ { "$ref": "#/$defs/s2fBase" },
334
+ {
335
+ "if": { "type": "object", "properties": { "form": { "const": "evm" } }, "required": ["form"] },
336
+ "then": { "type": "object", "required": ["ticket", "ticketSig"], "properties": { "ticket": { "$ref": "#/$defs/ticket" }, "ticketSig": { "$ref": "#/$defs/sig65" } } }
337
+ },
338
+ {
339
+ "if": { "type": "object", "properties": { "form": { "const": "canton" } }, "required": ["form"] },
340
+ "then": { "type": "object", "required": ["deliveryOrderCid", "validUntil"], "properties": { "deliveryOrderCid": { "type": "string", "minLength": 1 }, "validUntil": { "$ref": "#/$defs/timeS" } } }
341
+ }
342
+ ]
343
+ },
344
+ "ticket.receipt": {
345
+ "x-direction": "F2S",
346
+ "type": "object",
347
+ "description": "sig = TicketReceipt{ticketHash, ticketSigHash} by the filler address",
348
+ "allOf": [{ "$ref": "#/$defs/f2sBase" }],
349
+ "required": ["type", "orderHash", "attempt", "ticketHash", "ticketSigHash", "sig"],
350
+ "properties": {
351
+ "type": { "const": "ticket.receipt" },
352
+ "orderHash": { "$ref": "#/$defs/bytes32" },
353
+ "attempt": { "$ref": "#/$defs/uint32" },
354
+ "ticketHash": { "$ref": "#/$defs/bytes32" },
355
+ "ticketSigHash": { "$ref": "#/$defs/bytes32" },
356
+ "sig": { "$ref": "#/$defs/sig65" }
357
+ }
358
+ },
359
+ "fill.reported": {
360
+ "x-direction": "F2S",
361
+ "type": "object",
362
+ "allOf": [{ "$ref": "#/$defs/f2sBase" }],
363
+ "required": ["type", "orderHash", "attempt", "txRef"],
364
+ "properties": {
365
+ "type": { "const": "fill.reported" },
366
+ "orderHash": { "$ref": "#/$defs/bytes32" },
367
+ "attempt": { "$ref": "#/$defs/uint32" },
368
+ "txRef": { "type": "string", "minLength": 1, "description": "EVM tx hash or Canton update id" }
369
+ }
370
+ },
371
+ "ticket.expired": {
372
+ "x-direction": "S2F",
373
+ "type": "object",
374
+ "allOf": [{ "$ref": "#/$defs/s2fBase" }],
375
+ "required": ["type", "orderHash", "attempt", "result"],
376
+ "properties": {
377
+ "type": { "const": "ticket.expired" },
378
+ "orderHash": { "$ref": "#/$defs/bytes32" },
379
+ "attempt": { "$ref": "#/$defs/uint32" },
380
+ "result": { "$ref": "#/$defs/expiredResult" },
381
+ "exemptReason": { "$ref": "#/$defs/exemptReason" }
382
+ },
383
+ "if": { "type": "object", "properties": { "result": { "const": "EXEMPT" } }, "required": ["result"] },
384
+ "then": { "type": "object", "required": ["exemptReason"], "properties": { "exemptReason": true } }
385
+ },
386
+ "order.settled": {
387
+ "x-direction": "S2F",
388
+ "type": "object",
389
+ "allOf": [{ "$ref": "#/$defs/s2fBase" }],
390
+ "required": ["type", "orderHash", "payout", "fee", "penaltyWithheld", "txRef"],
391
+ "properties": {
392
+ "type": { "const": "order.settled" },
393
+ "orderHash": { "$ref": "#/$defs/bytes32" },
394
+ "payout": { "$ref": "#/$defs/uintDec256" },
395
+ "fee": { "$ref": "#/$defs/uintDec256" },
396
+ "penaltyWithheld": { "$ref": "#/$defs/uintDec256" },
397
+ "txRef": { "type": "string", "minLength": 1 }
398
+ }
399
+ },
400
+ "penalty.applied": {
401
+ "x-direction": "S2F",
402
+ "type": "object",
403
+ "allOf": [{ "$ref": "#/$defs/s2fBase" }],
404
+ "required": ["type", "violationId", "code", "step", "details"],
405
+ "properties": {
406
+ "type": { "const": "penalty.applied" },
407
+ "violationId": { "type": "string", "minLength": 1 },
408
+ "code": { "type": "string", "minLength": 1 },
409
+ "step": { "$ref": "#/$defs/penaltyStep" },
410
+ "details": { "type": "object" }
411
+ }
412
+ }
413
+ }
414
+ }
@@ -0,0 +1,93 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://cancore.io/schemas/filler-protocol/v1/records.schema.json",
4
+ "title": "Cancore filler protocol v1 — public records",
5
+ "$comment": "The draw record (GET /v1/draws/{orderHash}), the epoch record (GET /v1/draws/epochs/{id}) — auction-and-draw §3.3–3.4 — and the gateway identity (GET /v1/gateway). Records are signed by the gateway like an S→F frame (sig over GatewayMessage{keccak256(JCS(record without sig))}) but are public: no fillerId, no sentAt.",
6
+ "$defs": {
7
+ "drawCandidate": {
8
+ "type": "object",
9
+ "required": ["fillerId", "weight"],
10
+ "properties": { "fillerId": { "$ref": "messages.schema.json#/$defs/fillerId" }, "weight": { "$ref": "messages.schema.json#/$defs/uintDec256" } }
11
+ },
12
+ "drawAttempt": {
13
+ "type": "object",
14
+ "required": ["attempt", "tBase", "closedBy", "drandRound", "drandRandomness", "drandSignature", "candidates", "r", "winnerFillerId", "fallbackReason"],
15
+ "properties": {
16
+ "attempt": { "$ref": "messages.schema.json#/$defs/uint32" },
17
+ "tBase": { "$ref": "messages.schema.json#/$defs/timeS" },
18
+ "closedBy": { "anyOf": [{ "enum": ["OFFER_TIMEOUT", "OFFER_DECLINE", "TICKET_DECLINE", "TICKET_EXPIRED", "FILLED", null] }, { "$ref": "messages.schema.json#/$defs/futureEnumValue" }] },
19
+ "drandRound": { "$ref": "messages.schema.json#/$defs/uintDec64" },
20
+ "drandRandomness": { "$ref": "messages.schema.json#/$defs/bytes32" },
21
+ "drandSignature": { "type": "string", "pattern": "^0x[0-9a-f]{96}$", "description": "BLS signature of the round, 48 bytes (G1)" },
22
+ "candidates": { "type": "array", "items": { "$ref": "#/$defs/drawCandidate" }, "description": "ascending by the UTF-8 bytes of fillerId (A-22)" },
23
+ "r": { "$ref": "messages.schema.json#/$defs/uintDec256" },
24
+ "winnerFillerId": { "$ref": "messages.schema.json#/$defs/fillerId" },
25
+ "fallbackReason": { "anyOf": [{ "enum": ["DRAW_FALLBACK", null] }, { "$ref": "messages.schema.json#/$defs/futureEnumValue" }] }
26
+ }
27
+ },
28
+ "drawRecord": {
29
+ "type": "object",
30
+ "required": ["orderHash", "source", "openRef", "t0", "epochId", "deltaDrand", "attempts", "sig"],
31
+ "properties": {
32
+ "orderHash": { "$ref": "messages.schema.json#/$defs/bytes32" },
33
+ "source": { "$ref": "messages.schema.json#/$defs/caip2" },
34
+ "openRef": { "type": "string", "minLength": 1, "description": "EVM: open tx hash; Canton: Execute update id" },
35
+ "t0": { "$ref": "messages.schema.json#/$defs/timeS" },
36
+ "epochId": { "$ref": "messages.schema.json#/$defs/uintDec64" },
37
+ "deltaDrand": { "$ref": "messages.schema.json#/$defs/uint32", "description": "seconds" },
38
+ "attempts": { "type": "array", "items": { "$ref": "#/$defs/drawAttempt" } },
39
+ "sig": { "$ref": "messages.schema.json#/$defs/sig65" }
40
+ }
41
+ },
42
+ "epochLeaf": {
43
+ "type": "object",
44
+ "description": "StandardMerkleTree leaf [\"string\", \"uint256\", \"uint8\", \"uint16\"] = (fillerId, base, tier, reliabilityBps)",
45
+ "required": ["fillerId", "base", "tier", "reliabilityBps"],
46
+ "properties": {
47
+ "fillerId": { "$ref": "messages.schema.json#/$defs/fillerId" },
48
+ "base": { "$ref": "messages.schema.json#/$defs/uintDec256" },
49
+ "tier": { "$ref": "messages.schema.json#/$defs/uint8" },
50
+ "reliabilityBps": { "type": "integer", "minimum": 0, "maximum": 10000 }
51
+ }
52
+ },
53
+ "stakeStep": {
54
+ "type": "object",
55
+ "required": ["tier", "minStake", "step"],
56
+ "properties": {
57
+ "tier": { "$ref": "messages.schema.json#/$defs/uint8" },
58
+ "minStake": { "$ref": "messages.schema.json#/$defs/uintDec256" },
59
+ "step": { "$ref": "messages.schema.json#/$defs/uintDec256" }
60
+ }
61
+ },
62
+ "epochRecord": {
63
+ "type": "object",
64
+ "required": ["epochId", "startsAt", "endsAt", "weightsRoot", "leaves", "stakeSteps", "rMinBps", "snapshotBlocks", "sig"],
65
+ "properties": {
66
+ "epochId": { "$ref": "messages.schema.json#/$defs/uintDec64" },
67
+ "startsAt": { "$ref": "messages.schema.json#/$defs/timeS" },
68
+ "endsAt": { "$ref": "messages.schema.json#/$defs/timeS" },
69
+ "weightsRoot": { "$ref": "messages.schema.json#/$defs/bytes32" },
70
+ "leaves": { "type": "array", "items": { "$ref": "#/$defs/epochLeaf" } },
71
+ "stakeSteps": { "type": "array", "items": { "$ref": "#/$defs/stakeStep" } },
72
+ "rMinBps": { "type": "integer", "minimum": 0, "maximum": 10000 },
73
+ "snapshotBlocks": {
74
+ "type": "object",
75
+ "propertyNames": { "$ref": "messages.schema.json#/$defs/caip2" },
76
+ "additionalProperties": { "$ref": "messages.schema.json#/$defs/uintDec64" }
77
+ },
78
+ "sig": { "$ref": "messages.schema.json#/$defs/sig65" }
79
+ }
80
+ },
81
+ "gatewayInfo": {
82
+ "type": "object",
83
+ "description": "GET /v1/gateway: the mirror of @cancore/contracts FILLER_GATEWAYS for this environment. A taker trusts the package, and uses this to notice a rotation",
84
+ "required": ["env", "gateway", "ticketSigners", "protocolVersion"],
85
+ "properties": {
86
+ "env": { "type": "string", "minLength": 1 },
87
+ "gateway": { "$ref": "messages.schema.json#/$defs/address" },
88
+ "ticketSigners": { "type": "array", "items": { "$ref": "messages.schema.json#/$defs/address" } },
89
+ "protocolVersion": { "$ref": "messages.schema.json#/$defs/protocolVersion" }
90
+ }
91
+ }
92
+ }
93
+ }
@@ -0,0 +1,115 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://cancore.io/schemas/filler-protocol/v1/rest.schema.json",
4
+ "title": "Cancore filler protocol v1 — REST fallback",
5
+ "$comment": "protocol §3.6. Bodies are the WebSocket frames (S→F responses carry the gateway sig). /v1/filler/* needs `Authorization: Bearer <token>` from POST /v1/filler/auth; the token is bound to the fillerId it was issued for, and a ticket of another filler is 404 UNKNOWN_TICKET. /v1/draws/* and /v1/gateway are public. Every non-2xx body is the `error` frame, with the HTTP status of x-error-status. x-endpoints: request/response name a $def here or in messages.schema.json.",
6
+ "x-endpoints": [
7
+ { "method": "GET", "path": "/v1/filler/auth/challenge", "auth": "none", "response": "messages.schema.json#/$defs/auth.challenge" },
8
+ { "method": "POST", "path": "/v1/filler/auth", "auth": "none", "request": "messages.schema.json#/$defs/auth.response", "response": "#/$defs/authToken" },
9
+ { "method": "GET", "path": "/v1/filler/tickets", "auth": "bearer", "query": "#/$defs/ticketListQuery", "response": "#/$defs/ticketList" },
10
+ { "method": "POST", "path": "/v1/filler/tickets/{orderHash}/{attempt}/intent", "auth": "bearer", "request": "messages.schema.json#/$defs/ticket.intent", "response": "messages.schema.json#/$defs/ticket.intent.ack" },
11
+ { "method": "POST", "path": "/v1/filler/tickets/{orderHash}/{attempt}/receipt", "auth": "bearer", "request": "messages.schema.json#/$defs/ticket.receipt", "response": "#/$defs/empty" },
12
+ { "method": "POST", "path": "/v1/filler/tickets/{orderHash}/{attempt}/decline", "auth": "bearer", "request": "messages.schema.json#/$defs/ticket.decline", "response": "#/$defs/empty" },
13
+ { "method": "POST", "path": "/v1/filler/stake-bindings", "auth": "bearer", "request": "#/$defs/stakeBindingRequest", "response": "#/$defs/empty" },
14
+ { "method": "GET", "path": "/v1/filler/quotes", "auth": "bearer", "query": "#/$defs/quoteListQuery", "response": "#/$defs/quoteList" },
15
+ { "method": "GET", "path": "/v1/filler/stats", "auth": "bearer", "response": "#/$defs/fillerStats" },
16
+ { "method": "GET", "path": "/v1/filler/penalties", "auth": "bearer", "query": "#/$defs/pageQuery", "response": "#/$defs/penaltyList" },
17
+ { "method": "GET", "path": "/v1/draws/{orderHash}", "auth": "none", "response": "records.schema.json#/$defs/drawRecord" },
18
+ { "method": "GET", "path": "/v1/draws/epochs/{id}", "auth": "none", "response": "records.schema.json#/$defs/epochRecord" },
19
+ { "method": "GET", "path": "/v1/gateway", "auth": "none", "response": "records.schema.json#/$defs/gatewayInfo" }
20
+ ],
21
+ "x-error-status": {
22
+ "BAD_REQUEST": 400, "UNAUTHENTICATED": 401, "UNSUPPORTED_VERSION": 400, "UNSUPPORTED_TYPE": 400, "BAD_SIGNATURE": 422,
23
+ "UNKNOWN_REQUEST": 404, "UNKNOWN_TICKET": 404, "TICKET_CLOSED": 409, "NOT_ELIGIBLE": 403, "RATE_LIMITED": 429, "INTERNAL": 500
24
+ },
25
+ "$defs": {
26
+ "errorBody": { "$ref": "messages.schema.json#/$defs/error" },
27
+ "empty": { "type": "object", "description": "no fields in v1; receivers ignore unknown ones (V-2)" },
28
+ "authToken": {
29
+ "type": "object",
30
+ "required": ["token", "expiresAt"],
31
+ "properties": { "token": { "type": "string", "minLength": 1 }, "expiresAt": { "$ref": "messages.schema.json#/$defs/timeMs" } }
32
+ },
33
+ "pageQuery": {
34
+ "type": "object",
35
+ "properties": { "cursor": { "type": "string", "minLength": 1 }, "limit": { "type": "string", "pattern": "^([1-9][0-9]?|100)$", "description": "1..100, default 50" } }
36
+ },
37
+ "ticketListQuery": {
38
+ "allOf": [{ "$ref": "#/$defs/pageQuery" }],
39
+ "type": "object",
40
+ "properties": { "status": { "enum": ["OFFERED", "ISSUED"], "description": "a request filter: the gateway owns the list, so it is closed" } }
41
+ },
42
+ "quoteListQuery": {
43
+ "allOf": [{ "$ref": "#/$defs/pageQuery" }],
44
+ "type": "object",
45
+ "properties": { "since": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "unix ms" } }
46
+ },
47
+ "ticketList": {
48
+ "type": "object",
49
+ "required": ["items", "nextCursor"],
50
+ "properties": {
51
+ "items": {
52
+ "type": "array",
53
+ "items": { "oneOf": [{ "$ref": "messages.schema.json#/$defs/ticket.offer" }, { "$ref": "messages.schema.json#/$defs/ticket.issued" }] }
54
+ },
55
+ "nextCursor": { "type": ["string", "null"] }
56
+ }
57
+ },
58
+ "stakeBindingRequest": {
59
+ "type": "object",
60
+ "description": "sig = StakeBinding{partnerId, stakingAddress, chainId, nonce} by the staking address",
61
+ "required": ["partnerId", "stakingAddress", "chainId", "nonce", "sig"],
62
+ "properties": {
63
+ "partnerId": { "$ref": "messages.schema.json#/$defs/fillerId" },
64
+ "stakingAddress": { "$ref": "messages.schema.json#/$defs/address" },
65
+ "chainId": { "$ref": "messages.schema.json#/$defs/uintDec256" },
66
+ "nonce": { "$ref": "messages.schema.json#/$defs/uintDec64" },
67
+ "sig": { "$ref": "messages.schema.json#/$defs/sig65" }
68
+ }
69
+ },
70
+ "quoteRecord": {
71
+ "type": "object",
72
+ "required": ["quote", "ack", "status"],
73
+ "properties": {
74
+ "quote": { "$ref": "messages.schema.json#/$defs/quote" },
75
+ "ack": { "$ref": "messages.schema.json#/$defs/quote.ack" },
76
+ "status": { "anyOf": [{ "enum": ["COUNTED", "LATE", "SHORT_TTL", "REPLACED", "BAD_SIG", "OUTLIER", "IN_BAND", "OUT_OF_BAND", "WON", "LOST"] }, { "$ref": "messages.schema.json#/$defs/futureEnumValue" }] }
77
+ }
78
+ },
79
+ "quoteList": {
80
+ "type": "object",
81
+ "required": ["items", "nextCursor"],
82
+ "properties": { "items": { "type": "array", "items": { "$ref": "#/$defs/quoteRecord" } }, "nextCursor": { "type": ["string", "null"] } }
83
+ },
84
+ "fillerStats": {
85
+ "type": "object",
86
+ "required": ["won", "delivered", "noShow", "reliability", "capacityUsd", "inFlightUsd"],
87
+ "properties": {
88
+ "won": { "type": "integer", "minimum": 0 },
89
+ "delivered": { "type": "integer", "minimum": 0 },
90
+ "noShow": { "type": "integer", "minimum": 0 },
91
+ "reliability": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "basis points" },
92
+ "capacityUsd": { "$ref": "messages.schema.json#/$defs/intDecUsd" },
93
+ "inFlightUsd": { "$ref": "messages.schema.json#/$defs/intDecUsd" }
94
+ }
95
+ },
96
+ "penaltyRecord": {
97
+ "type": "object",
98
+ "required": ["violationId", "code", "step", "at", "details"],
99
+ "properties": {
100
+ "violationId": { "type": "string", "minLength": 1 },
101
+ "code": { "type": "string", "minLength": 1 },
102
+ "step": { "$ref": "messages.schema.json#/$defs/penaltyStep" },
103
+ "orderHash": { "$ref": "messages.schema.json#/$defs/bytes32" },
104
+ "attempt": { "$ref": "messages.schema.json#/$defs/uint32" },
105
+ "at": { "$ref": "messages.schema.json#/$defs/timeMs" },
106
+ "details": { "type": "object" }
107
+ }
108
+ },
109
+ "penaltyList": {
110
+ "type": "object",
111
+ "required": ["items", "nextCursor"],
112
+ "properties": { "items": { "type": "array", "items": { "$ref": "#/$defs/penaltyRecord" } }, "nextCursor": { "type": ["string", "null"] } }
113
+ }
114
+ }
115
+ }