@cancore/contracts 0.2.0-rc.7 → 0.2.0-rc.9
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.
- package/README.md +149 -7
- package/dist/index.d.ts +388 -15
- package/dist/index.js +370 -115
- package/dist/index.js.map +1 -1
- package/package.json +2 -2
- package/spec/constants.json +66 -0
- package/spec/protocol/asyncapi.json +70 -95
- package/spec/protocol/messages.schema.json +30 -13
- package/spec/protocol/rest.schema.json +19 -3
- package/spec/protocol/typed-data/CantonTicketReceipt.json +77 -0
- package/spec/protocol/typed-data/GatewayMessage.json +5 -4
- package/spec/protocol/vectors/messages.json +28 -3
- package/spec/vectors/canton-destination.json +59 -0
- package/spec/vectors/evm-order.json +48 -0
- package/spec/vectors/fee-split.json +179 -0
- package/spec/vectors/permit-witness.json +144 -0
package/dist/index.js
CHANGED
|
@@ -217,6 +217,48 @@ function hashFillProof(proof, chainId, verifyingContract) {
|
|
|
217
217
|
return hashTypedData({ domain: fillProofDomain(chainId, verifyingContract), types: FILL_PROOF_TYPES, primaryType: "FillProof", message: { ...proof } });
|
|
218
218
|
}
|
|
219
219
|
|
|
220
|
+
// src/constants.ts
|
|
221
|
+
var BPS = 1e4;
|
|
222
|
+
var MAX_FEE_BPS = 1e3;
|
|
223
|
+
var MIN_FILL_TTL = 60;
|
|
224
|
+
var MAX_FILL_TTL = 86400;
|
|
225
|
+
var MAX_SIG_TTL = 86400;
|
|
226
|
+
var MAX_PROOF_WINDOW = 14400;
|
|
227
|
+
var GRACE = MAX_FILL_TTL + MAX_PROOF_WINDOW;
|
|
228
|
+
var SET_DELAY = 259200;
|
|
229
|
+
var EIP2294_MAX_CHAIN_ID = 9223372036854775771n;
|
|
230
|
+
var CANTON_ORIGIN_ID = {
|
|
231
|
+
mainnet: 9223372036854775809n,
|
|
232
|
+
testnet: 9223372036854775810n,
|
|
233
|
+
devnet: 9223372036854775811n
|
|
234
|
+
};
|
|
235
|
+
var CANTON_SOURCE_ANCHOR = "0x2f37b46Ea93001829498b145985fb53028033701";
|
|
236
|
+
var OWNER_LABEL_TAG = "cancore:owner:v1";
|
|
237
|
+
var INSTRUMENT_LABEL_TAG = "cancore:instrument:v1";
|
|
238
|
+
var DAML_NUMERIC_SCALE = 10;
|
|
239
|
+
function exactUnits(value, decimals, field) {
|
|
240
|
+
if (typeof value !== "string" || !/^\d+(\.\d+)?$/.test(value)) throw new TypeError(`${field}: not a plain decimal string: ${String(value)}`);
|
|
241
|
+
if (!Number.isSafeInteger(decimals) || decimals < 0) throw new TypeError(`${field}: decimals must be a non-negative integer`);
|
|
242
|
+
const [whole, fraction = ""] = value.split(".");
|
|
243
|
+
if (fraction.length > decimals) throw new RangeError(`${field}: ${value} does not fit ${decimals} decimals exactly`);
|
|
244
|
+
return BigInt(whole + fraction.padEnd(decimals, "0"));
|
|
245
|
+
}
|
|
246
|
+
function abiEncodeStrings(values) {
|
|
247
|
+
const tails = values.map((v) => {
|
|
248
|
+
const bytes = utf8ToBytes(v);
|
|
249
|
+
const body = new Uint8Array(Math.ceil(bytes.length / 32) * 32);
|
|
250
|
+
body.set(bytes);
|
|
251
|
+
return concatBytes(beBytes(BigInt(bytes.length), 32), body);
|
|
252
|
+
});
|
|
253
|
+
let offset = BigInt(values.length * 32);
|
|
254
|
+
const heads = tails.map((t) => {
|
|
255
|
+
const head = beBytes(offset, 32);
|
|
256
|
+
offset += BigInt(t.length);
|
|
257
|
+
return head;
|
|
258
|
+
});
|
|
259
|
+
return concatBytes(...heads, ...tails);
|
|
260
|
+
}
|
|
261
|
+
|
|
220
262
|
// src/protocol/typedData.ts
|
|
221
263
|
var FILLER_PROTOCOL_DOMAIN = { name: "CancoreFillerProtocol", version: "1" };
|
|
222
264
|
var FILL_TICKET_DOMAIN = { name: "CancoreFillTicket", version: "1" };
|
|
@@ -281,6 +323,14 @@ var TICKET_RECEIPT_TYPES = {
|
|
|
281
323
|
{ name: "ticketSigHash", type: "bytes32" }
|
|
282
324
|
]
|
|
283
325
|
};
|
|
326
|
+
var CANTON_TICKET_RECEIPT_TYPES = {
|
|
327
|
+
CantonTicketReceipt: [
|
|
328
|
+
{ name: "orderHash", type: "bytes32" },
|
|
329
|
+
{ name: "attempt", type: "uint32" },
|
|
330
|
+
{ name: "deliveryOrderCidHash", type: "bytes32" },
|
|
331
|
+
{ name: "validUntil", type: "uint64" }
|
|
332
|
+
]
|
|
333
|
+
};
|
|
284
334
|
var STAKE_BINDING_TYPES = {
|
|
285
335
|
StakeBinding: [
|
|
286
336
|
{ name: "partnerId", type: "string" },
|
|
@@ -309,6 +359,152 @@ var FILLER_KEY_REGISTRATION_TYPES = {
|
|
|
309
359
|
{ name: "issuedAt", type: "uint64" }
|
|
310
360
|
]
|
|
311
361
|
};
|
|
362
|
+
|
|
363
|
+
// src/order.ts
|
|
364
|
+
function hashOrder(order, domain) {
|
|
365
|
+
return hashTypedData({ domain: routerDomain(domain.chainId, domain.verifyingContract), types: ORDER_TYPES, primaryType: "Order", message: { ...order } });
|
|
366
|
+
}
|
|
367
|
+
function isCantonOriginId(chainId) {
|
|
368
|
+
let id;
|
|
369
|
+
try {
|
|
370
|
+
id = uint(chainId, 64, "chainId");
|
|
371
|
+
} catch {
|
|
372
|
+
return false;
|
|
373
|
+
}
|
|
374
|
+
return Object.values(CANTON_ORIGIN_ID).includes(id);
|
|
375
|
+
}
|
|
376
|
+
function sourceOrderHash(order, sourceRouter) {
|
|
377
|
+
const router = sourceRouter ?? (isCantonOriginId(order.originChainId) ? CANTON_SOURCE_ANCHOR : void 0);
|
|
378
|
+
if (router === void 0) throw new Error(`sourceOrderHash: no source router for originChainId ${String(order.originChainId)} (SourceRouterUnknown)`);
|
|
379
|
+
return hashOrder(order, { chainId: order.originChainId, verifyingContract: router });
|
|
380
|
+
}
|
|
381
|
+
function buildCantonSourceOrder(intent) {
|
|
382
|
+
for (const field of ["ownerPartyId", "requestId", "instrumentAdmin", "instrumentId"]) {
|
|
383
|
+
if (typeof intent[field] !== "string" || intent[field].length === 0) throw new TypeError(`${field}: a non-empty string`);
|
|
384
|
+
}
|
|
385
|
+
const originChainId = uint(intent.cantonOriginId, 64, "cantonOriginId");
|
|
386
|
+
if (originChainId <= EIP2294_MAX_CHAIN_ID) throw new RangeError(`cantonOriginId: ${originChainId} collides with the EVM chain-id range`);
|
|
387
|
+
const feeBps = exactUnits(intent.feeRate, 4, "feeRate");
|
|
388
|
+
if (feeBps > BigInt(MAX_FEE_BPS)) throw new RangeError(`feeRate: ${intent.feeRate} exceeds MAX_FEE_BPS`);
|
|
389
|
+
const order = {
|
|
390
|
+
user: label(OWNER_LABEL_TAG, intent.ownerPartyId, intent.requestId),
|
|
391
|
+
originChainId: originChainId.toString(),
|
|
392
|
+
inputToken: label(INSTRUMENT_LABEL_TAG, intent.instrumentAdmin, intent.instrumentId),
|
|
393
|
+
inputAmount: exactUnits(intent.amount, DAML_NUMERIC_SCALE, "amount").toString(),
|
|
394
|
+
destination: toHex(beBytes(uint(intent.destinationChainId, 256, "destinationChainId"), 32)),
|
|
395
|
+
outputAsset: addressWord(intent.wantToken, "wantToken"),
|
|
396
|
+
minReceived: exactUnits(intent.minReceived, intent.wantDecimals, "minReceived").toString(),
|
|
397
|
+
recipient: addressWord(intent.recipient, "recipient"),
|
|
398
|
+
createdAt: wholeSecond(intent.createdAt, "createdAt"),
|
|
399
|
+
fillDeadline: wholeSecond(intent.fillDeadline, "fillDeadline"),
|
|
400
|
+
feeBps: feeBps.toString()
|
|
401
|
+
};
|
|
402
|
+
const domain = { name: "CancoreRouter", version: "1", chainId: originChainId.toString(), verifyingContract: CANTON_SOURCE_ANCHOR };
|
|
403
|
+
return { order, domain, orderHash: hashOrder(order, domain) };
|
|
404
|
+
}
|
|
405
|
+
var TOKEN_PERMISSIONS_TYPES = {
|
|
406
|
+
TokenPermissions: [
|
|
407
|
+
{ name: "token", type: "address" },
|
|
408
|
+
{ name: "amount", type: "uint256" }
|
|
409
|
+
]
|
|
410
|
+
};
|
|
411
|
+
var PERMIT2_WITNESS_TYPE_STRING = `Order witness)${encodeType(ORDER_TYPES, "Order")}${encodeType(TOKEN_PERMISSIONS_TYPES, "TokenPermissions")}`;
|
|
412
|
+
var PERMIT_WITNESS_TYPEHASH = keccak(
|
|
413
|
+
utf8ToBytes(`PermitWitnessTransferFrom(TokenPermissions permitted,address spender,uint256 nonce,uint256 deadline,${PERMIT2_WITNESS_TYPE_STRING}`)
|
|
414
|
+
);
|
|
415
|
+
var PERMIT_WITNESS_TYPES = {
|
|
416
|
+
PermitWitnessTransferFrom: [
|
|
417
|
+
{ name: "permitted", type: "TokenPermissions" },
|
|
418
|
+
{ name: "spender", type: "address" },
|
|
419
|
+
{ name: "nonce", type: "uint256" },
|
|
420
|
+
{ name: "deadline", type: "uint256" },
|
|
421
|
+
{ name: "witness", type: "Order" }
|
|
422
|
+
],
|
|
423
|
+
...TOKEN_PERMISSIONS_TYPES,
|
|
424
|
+
...ORDER_TYPES
|
|
425
|
+
};
|
|
426
|
+
function permit2Domain(chainId, permit2 = PERMIT2_ADDRESS) {
|
|
427
|
+
return { name: "Permit2", chainId, verifyingContract: permit2 };
|
|
428
|
+
}
|
|
429
|
+
function hashPermitWitness(permit, chainId, permit2 = PERMIT2_ADDRESS) {
|
|
430
|
+
const struct = keccak(
|
|
431
|
+
concatBytes(
|
|
432
|
+
PERMIT_WITNESS_TYPEHASH,
|
|
433
|
+
hexBytes(hashStruct(TOKEN_PERMISSIONS_TYPES, "TokenPermissions", permit.permitted), "permitted", 32),
|
|
434
|
+
hexBytes(addressWord(permit.spender, "spender"), "spender", 32),
|
|
435
|
+
beBytes(uint(permit.nonce, 256, "nonce"), 32),
|
|
436
|
+
beBytes(uint(permit.deadline, 256, "deadline"), 32),
|
|
437
|
+
hexBytes(hashStruct(ORDER_TYPES, "Order", { ...permit.witness }), "witness", 32)
|
|
438
|
+
)
|
|
439
|
+
);
|
|
440
|
+
const separator = hexBytes(hashDomain(permit2Domain(chainId, permit2)), "domain", 32);
|
|
441
|
+
return toHex(keccak(concatBytes(new Uint8Array([25, 1]), separator, struct)));
|
|
442
|
+
}
|
|
443
|
+
function wholeSecond(value, field) {
|
|
444
|
+
return uint(value, 64, `${field} (a whole second)`).toString();
|
|
445
|
+
}
|
|
446
|
+
function addressWord(value, field) {
|
|
447
|
+
const address = checksumAddress(value, field);
|
|
448
|
+
return `0x${"00".repeat(12)}${address.slice(2).toLowerCase()}`;
|
|
449
|
+
}
|
|
450
|
+
function checksumAddress(value, field) {
|
|
451
|
+
hexBytes(value, field, 20);
|
|
452
|
+
const lower = value.slice(2).toLowerCase();
|
|
453
|
+
const hash = toHex(keccak(utf8ToBytes(lower))).slice(2);
|
|
454
|
+
const sum = `0x${[...lower].map((c, i) => parseInt(hash[i], 16) >= 8 ? c.toUpperCase() : c).join("")}`;
|
|
455
|
+
const body = value.slice(2);
|
|
456
|
+
if (body !== body.toLowerCase() && body !== body.toUpperCase() && `0x${body}` !== sum) throw new TypeError(`${field}: bad EIP-55 checksum: ${String(value)}`);
|
|
457
|
+
return sum;
|
|
458
|
+
}
|
|
459
|
+
function label(tag, a, b) {
|
|
460
|
+
const hash = toHex(keccak(abiEncodeStrings([tag, a, b])));
|
|
461
|
+
return checksumAddress(`0x${hash.slice(-40)}`, "label");
|
|
462
|
+
}
|
|
463
|
+
|
|
464
|
+
// src/fee.ts
|
|
465
|
+
function operands(total, feeBps) {
|
|
466
|
+
const t = uint(total, 256, "total");
|
|
467
|
+
const bps = uint(feeBps, 16, "feeBps");
|
|
468
|
+
if (bps > BigInt(MAX_FEE_BPS)) throw new RangeError(`feeBps: ${bps} exceeds MAX_FEE_BPS (${MAX_FEE_BPS})`);
|
|
469
|
+
return [t, bps];
|
|
470
|
+
}
|
|
471
|
+
function inclusiveFeeSplit(total, feeBps) {
|
|
472
|
+
const [t, bps] = operands(total, feeBps);
|
|
473
|
+
const payout = t * BigInt(BPS) / (BigInt(BPS) + bps);
|
|
474
|
+
return { payout, fee: t - payout };
|
|
475
|
+
}
|
|
476
|
+
function cantonInclusiveFeeSplit(total, feeBps) {
|
|
477
|
+
const [t, bps] = operands(total, feeBps);
|
|
478
|
+
const n = t * BigInt(BPS);
|
|
479
|
+
const d = BigInt(BPS) + bps;
|
|
480
|
+
const q = n / d;
|
|
481
|
+
const r = n - q * d;
|
|
482
|
+
const payout = 2n * r > d || 2n * r === d && q % 2n === 1n ? q + 1n : q;
|
|
483
|
+
return { payout, fee: t - payout };
|
|
484
|
+
}
|
|
485
|
+
var NETWORKS2 = Object.keys(CANTON_ORIGIN_ID);
|
|
486
|
+
var utf8Hash = (text) => toHex(keccak(utf8ToBytes(text)));
|
|
487
|
+
var nonEmpty = (value, field) => {
|
|
488
|
+
if (typeof value !== "string" || value.length === 0) throw new TypeError(`${field}: a non-empty string`);
|
|
489
|
+
return value;
|
|
490
|
+
};
|
|
491
|
+
function encodeCantonDestination(network) {
|
|
492
|
+
if (!NETWORKS2.includes(network)) throw new TypeError(`network: one of ${NETWORKS2.join(", ")}, got ${JSON.stringify(network)}`);
|
|
493
|
+
return utf8Hash(`canton:${network}`);
|
|
494
|
+
}
|
|
495
|
+
function cantonNetworkOfDestination(destination) {
|
|
496
|
+
const word = typeof destination === "string" ? destination.toLowerCase() : "";
|
|
497
|
+
return NETWORKS2.find((network) => encodeCantonDestination(network) === word);
|
|
498
|
+
}
|
|
499
|
+
function encodeCantonOutputAsset(instrument) {
|
|
500
|
+
return toHex(keccak(abiEncodeStrings([INSTRUMENT_LABEL_TAG, nonEmpty(instrument.admin, "instrument.admin"), nonEmpty(instrument.id, "instrument.id")])));
|
|
501
|
+
}
|
|
502
|
+
function encodeCantonRecipient(partyId) {
|
|
503
|
+
return utf8Hash(nonEmpty(partyId, "partyId"));
|
|
504
|
+
}
|
|
505
|
+
function encodeCantonAmount(amount) {
|
|
506
|
+
return exactUnits(amount, DAML_NUMERIC_SCALE, "amount");
|
|
507
|
+
}
|
|
312
508
|
var FILLER_ID_PATTERN = /^[a-z0-9][a-z0-9-]{0,62}$/;
|
|
313
509
|
var SECP256K1_N = 0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141n;
|
|
314
510
|
function fillerIdHash(fillerId) {
|
|
@@ -338,13 +534,25 @@ function isEoaSignature(sig) {
|
|
|
338
534
|
const s = BigInt(`0x${sig.slice(66, 130)}`);
|
|
339
535
|
return r > 0n && r < SECP256K1_N && s > 0n && s <= SECP256K1_N / 2n;
|
|
340
536
|
}
|
|
341
|
-
|
|
342
|
-
// src/protocol/digests.ts
|
|
343
537
|
var hashFillTicket = (ticket) => hashTypedData({ domain: FILL_TICKET_DOMAIN, types: FILL_TICKET_TYPES, primaryType: "FillTicket", message: { ...ticket } });
|
|
344
538
|
var hashFillerQuote = (quote) => hashTypedData({ domain: FILLER_PROTOCOL_DOMAIN, types: FILLER_QUOTE_TYPES, primaryType: "FillerQuote", message: { ...quote } });
|
|
345
539
|
var hashTicketIntent = (intent) => hashTypedData({ domain: FILLER_PROTOCOL_DOMAIN, types: TICKET_INTENT_TYPES, primaryType: "TicketIntent", message: { ...intent } });
|
|
346
540
|
var hashFillerMessage = (message) => hashTypedData({ domain: FILLER_PROTOCOL_DOMAIN, types: FILLER_MESSAGE_TYPES, primaryType: "FillerMessage", message: { bodyHash: fillerMessageBodyHash(message) } });
|
|
347
541
|
var hashFillerKeyRegistration = (registration) => hashTypedData({ domain: FILLER_PROTOCOL_DOMAIN, types: FILLER_KEY_REGISTRATION_TYPES, primaryType: "FillerKeyRegistration", message: { ...registration } });
|
|
542
|
+
function deliveryOrderCidHash(deliveryOrderCid) {
|
|
543
|
+
if (typeof deliveryOrderCid !== "string" || deliveryOrderCid.length === 0) throw new TypeError("deliveryOrderCid: a Canton contract id is a non-empty string");
|
|
544
|
+
return toHex(keccak(utf8ToBytes(deliveryOrderCid)));
|
|
545
|
+
}
|
|
546
|
+
function cantonTicketReceipt(ticket) {
|
|
547
|
+
hexBytes(ticket.orderHash, "orderHash", 32);
|
|
548
|
+
return {
|
|
549
|
+
orderHash: ticket.orderHash.toLowerCase(),
|
|
550
|
+
attempt: Number(uint(ticket.attempt, 32, "attempt")),
|
|
551
|
+
deliveryOrderCidHash: deliveryOrderCidHash(ticket.deliveryOrderCid),
|
|
552
|
+
validUntil: uint(ticket.validUntil, 64, "validUntil").toString()
|
|
553
|
+
};
|
|
554
|
+
}
|
|
555
|
+
var hashCantonTicketReceipt = (receipt) => hashTypedData({ domain: FILLER_PROTOCOL_DOMAIN, types: CANTON_TICKET_RECEIPT_TYPES, primaryType: "CantonTicketReceipt", message: { ...receipt } });
|
|
348
556
|
|
|
349
557
|
// src/protocol/envelope.ts
|
|
350
558
|
function fillerEnvelopeError(message, ctx) {
|
|
@@ -395,6 +603,44 @@ function drawWinner(h, candidates) {
|
|
|
395
603
|
|
|
396
604
|
// src/protocol/gateway.ts
|
|
397
605
|
var PROTOCOL_VERSION = "1";
|
|
606
|
+
var FILLER_WS_SUBPROTOCOL = "cancore-filler.v1";
|
|
607
|
+
var FILLER_WS_BEARER_PREFIX = "bearer.";
|
|
608
|
+
function fillerWsProtocols(token) {
|
|
609
|
+
return [FILLER_WS_SUBPROTOCOL, `${FILLER_WS_BEARER_PREFIX}${token}`];
|
|
610
|
+
}
|
|
611
|
+
var FILLER_CLOSE_CODES = {
|
|
612
|
+
/** filler-gateway is shutting down. */
|
|
613
|
+
GOING_AWAY: 1001,
|
|
614
|
+
/** The filler missed its heartbeats. */
|
|
615
|
+
HEARTBEAT_MISSED: 4e3,
|
|
616
|
+
/** A newer session of this fillerId superseded this one. */
|
|
617
|
+
SUPERSEDED: 4001,
|
|
618
|
+
/** Cancore staff changed the message key the session was opened with: log in again with the new key. */
|
|
619
|
+
KEY_CHANGED: 4002,
|
|
620
|
+
/** The filler is no longer `ACTIVE` (suspended). */
|
|
621
|
+
NOT_ACTIVE: 4003,
|
|
622
|
+
/** This session's inbound queue overflowed (count or bytes); only this session is closed. */
|
|
623
|
+
QUEUE_OVERFLOW: 4008,
|
|
624
|
+
/**
|
|
625
|
+
* Sustained excess over the rate limits: every session of the fillerId is
|
|
626
|
+
* closed and its upgrades and bearer requests are refused for a cooldown;
|
|
627
|
+
* the `error RATE_LIMITED` sent just before carries `retryAfterMs` = the
|
|
628
|
+
* remaining cooldown.
|
|
629
|
+
*/
|
|
630
|
+
RATE_LIMITED: 4029
|
|
631
|
+
};
|
|
632
|
+
var FILLER_UPGRADE_REFUSALS = {
|
|
633
|
+
/** `cancore-filler.v1` not offered, or not exactly one `bearer.` entry. */
|
|
634
|
+
400: "BAD_REQUEST",
|
|
635
|
+
/** The token is missing, unknown or expired, or the message key changed. */
|
|
636
|
+
401: "UNAUTHENTICATED",
|
|
637
|
+
/** The filler is unknown or not `ACTIVE`. */
|
|
638
|
+
403: "NOT_ACTIVE",
|
|
639
|
+
/** The login rate class is over its limit, or the fillerId is cooling down; `Retry-After` in seconds. */
|
|
640
|
+
429: "RATE_LIMITED",
|
|
641
|
+
/** The replica is at its connection limit, or the fillerId already holds its maximum of live sessions. */
|
|
642
|
+
503: "UNAVAILABLE"
|
|
643
|
+
};
|
|
398
644
|
var FILLER_GATEWAYS = {
|
|
399
645
|
mainnet: { gateway: null, ticketSigners: [] },
|
|
400
646
|
testnet: { gateway: null, ticketSigners: [] },
|
|
@@ -478,7 +724,7 @@ var asyncapi_default = {
|
|
|
478
724
|
asyncapi: "3.0.0",
|
|
479
725
|
info: {
|
|
480
726
|
title: "Cancore filler protocol",
|
|
481
|
-
version: "1.0.0-rc.
|
|
727
|
+
version: "1.0.0-rc.2",
|
|
482
728
|
description: "The WebSocket protocol between a filler and the Cancore filler gateway, v1 (release candidate). Operations are the gateway's: it sends S\u2192F frames and receives F\u2192S frames. Every frame carries id, fillerId and sentAt and is signed in the CancoreFillerProtocol v1 domain: S\u2192F with sig = the gateway key over GatewayMessage{bodyHash}, F\u2192S with msgSig = the filler's message key over FillerMessage{bodyHash}, bodyHash = keccak256(JCS(frame without that field)). Payload schemas: messages.schema.json. Generated by scripts/gen-protocol-docs.mjs.",
|
|
483
729
|
license: {
|
|
484
730
|
name: "Apache-2.0"
|
|
@@ -500,14 +746,43 @@ var asyncapi_default = {
|
|
|
500
746
|
channels: {
|
|
501
747
|
filler: {
|
|
502
748
|
address: "/v1",
|
|
503
|
-
description: "One JSON object per text frame.
|
|
749
|
+
description: "One JSON object per text frame. Connect only after login: the filler logs in over REST (GET /v1/filler/auth/challenge?fillerId=, POST /v1/filler/auth \u2192 {token, expiresAt}, rest.schema.json) and offers two subprotocols on the upgrade, cancore-filler.v1 and bearer.<token>; Authorization and the query string are not read. filler-gateway checks them before the upgrade and refuses with a plain HTTP response (x-upgrade-refusals: no WebSocket, nothing signed, Retry-After in seconds on 429). On success it answers Sec-WebSocket-Protocol: cancore-filler.v1 (the token is never echoed), the session is authenticated from the first byte, and the first frame is a signed auth.ok. auth.challenge and auth.response never travel on the socket (auth.response here is UNSUPPORTED_TYPE). Over a per-fillerId rate limit a frame is dropped unverified and the filler gets error RATE_LIMITED with retryAfterMs at most once per window and rate class; sustained excess closes every session of the fillerId with 4029. Close codes: x-close-codes.",
|
|
750
|
+
bindings: {
|
|
751
|
+
ws: {
|
|
752
|
+
method: "GET",
|
|
753
|
+
headers: {
|
|
754
|
+
type: "object",
|
|
755
|
+
required: [
|
|
756
|
+
"Sec-WebSocket-Protocol"
|
|
757
|
+
],
|
|
758
|
+
properties: {
|
|
759
|
+
"Sec-WebSocket-Protocol": {
|
|
760
|
+
type: "string",
|
|
761
|
+
pattern: "^cancore-filler\\.v1, ?bearer\\.[A-Za-z0-9_-]+$|^bearer\\.[A-Za-z0-9_-]+, ?cancore-filler\\.v1$",
|
|
762
|
+
description: "cancore-filler.v1 and exactly one bearer.<token>, the token of POST /v1/filler/auth (base64url). The server selects cancore-filler.v1"
|
|
763
|
+
}
|
|
764
|
+
}
|
|
765
|
+
},
|
|
766
|
+
bindingVersion: "0.1.0"
|
|
767
|
+
}
|
|
768
|
+
},
|
|
769
|
+
"x-upgrade-refusals": {
|
|
770
|
+
"400": "cancore-filler.v1 not offered, or not exactly one bearer. entry",
|
|
771
|
+
"401": "token missing, unknown or expired, or the message key changed",
|
|
772
|
+
"403": "filler unknown or not ACTIVE",
|
|
773
|
+
"429": "login rate class over its limit, or the fillerId is cooling down; Retry-After (seconds, rounded up)",
|
|
774
|
+
"503": "the replica is at its connection limit, or the fillerId already holds its maximum of live sessions (across replicas)"
|
|
775
|
+
},
|
|
776
|
+
"x-close-codes": {
|
|
777
|
+
"1001": "filler-gateway shutting down",
|
|
778
|
+
"4000": "heartbeats missed",
|
|
779
|
+
"4001": "superseded by a newer session of this fillerId",
|
|
780
|
+
"4002": "the message key of the session was changed by staff",
|
|
781
|
+
"4003": "the filler is no longer ACTIVE (suspended)",
|
|
782
|
+
"4008": "this session's inbound queue overflowed (count or bytes); only this session",
|
|
783
|
+
"4029": "sustained over-limit: every session of the fillerId closed, cooling down; the error RATE_LIMITED sent just before carries retryAfterMs = the remaining cooldown"
|
|
784
|
+
},
|
|
504
785
|
messages: {
|
|
505
|
-
"auth.challenge": {
|
|
506
|
-
$ref: "#/components/messages/auth.challenge"
|
|
507
|
-
},
|
|
508
|
-
"auth.response": {
|
|
509
|
-
$ref: "#/components/messages/auth.response"
|
|
510
|
-
},
|
|
511
786
|
"auth.ok": {
|
|
512
787
|
$ref: "#/components/messages/auth.ok"
|
|
513
788
|
},
|
|
@@ -584,28 +859,6 @@ var asyncapi_default = {
|
|
|
584
859
|
}
|
|
585
860
|
},
|
|
586
861
|
operations: {
|
|
587
|
-
sendAuthChallenge: {
|
|
588
|
-
action: "send",
|
|
589
|
-
channel: {
|
|
590
|
-
$ref: "#/channels/filler"
|
|
591
|
-
},
|
|
592
|
-
messages: [
|
|
593
|
-
{
|
|
594
|
-
$ref: "#/channels/filler/messages/auth.challenge"
|
|
595
|
-
}
|
|
596
|
-
]
|
|
597
|
-
},
|
|
598
|
-
receiveAuthResponse: {
|
|
599
|
-
action: "receive",
|
|
600
|
-
channel: {
|
|
601
|
-
$ref: "#/channels/filler"
|
|
602
|
-
},
|
|
603
|
-
messages: [
|
|
604
|
-
{
|
|
605
|
-
$ref: "#/channels/filler/messages/auth.response"
|
|
606
|
-
}
|
|
607
|
-
]
|
|
608
|
-
},
|
|
609
862
|
sendAuthOk: {
|
|
610
863
|
action: "send",
|
|
611
864
|
channel: {
|
|
@@ -873,68 +1126,6 @@ var asyncapi_default = {
|
|
|
873
1126
|
},
|
|
874
1127
|
components: {
|
|
875
1128
|
messages: {
|
|
876
|
-
"auth.challenge": {
|
|
877
|
-
name: "auth.challenge",
|
|
878
|
-
title: "auth.challenge (S2F)",
|
|
879
|
-
payload: {
|
|
880
|
-
schemaFormat: "application/schema+json;version=draft-2020-12",
|
|
881
|
-
schema: {
|
|
882
|
-
$ref: "messages.schema.json#/$defs/auth.challenge"
|
|
883
|
-
}
|
|
884
|
-
},
|
|
885
|
-
examples: [
|
|
886
|
-
{
|
|
887
|
-
name: "auth-challenge-1",
|
|
888
|
-
payload: {
|
|
889
|
-
type: "auth.challenge",
|
|
890
|
-
id: "g-1",
|
|
891
|
-
sentAt: 178999998e4,
|
|
892
|
-
nonce: "0x63ed6389bd2a1d23bb678583c227172bda874e82b97b1c170bfeeb4373b4b0d5",
|
|
893
|
-
expiresAt: "1790000030",
|
|
894
|
-
sig: "0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001b"
|
|
895
|
-
}
|
|
896
|
-
}
|
|
897
|
-
]
|
|
898
|
-
},
|
|
899
|
-
"auth.response": {
|
|
900
|
-
name: "auth.response",
|
|
901
|
-
title: "auth.response (F2S)",
|
|
902
|
-
payload: {
|
|
903
|
-
schemaFormat: "application/schema+json;version=draft-2020-12",
|
|
904
|
-
schema: {
|
|
905
|
-
$ref: "messages.schema.json#/$defs/auth.response"
|
|
906
|
-
}
|
|
907
|
-
},
|
|
908
|
-
examples: [
|
|
909
|
-
{
|
|
910
|
-
name: "auth-response-1",
|
|
911
|
-
payload: {
|
|
912
|
-
type: "auth.response",
|
|
913
|
-
id: "a-1",
|
|
914
|
-
fillerId: "acme-markets",
|
|
915
|
-
sentAt: 1789999980100,
|
|
916
|
-
msgSig: "0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001b",
|
|
917
|
-
keyAddress: "0x90f79bf6eb2c4f870365e785982e1f101e93b906",
|
|
918
|
-
protocolVersion: "1",
|
|
919
|
-
sig: "0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001b"
|
|
920
|
-
}
|
|
921
|
-
},
|
|
922
|
-
{
|
|
923
|
-
name: "auth-response-2",
|
|
924
|
-
payload: {
|
|
925
|
-
type: "auth.response",
|
|
926
|
-
id: "a-2",
|
|
927
|
-
fillerId: "acme-markets",
|
|
928
|
-
sentAt: 1789999980100,
|
|
929
|
-
msgSig: "0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001b",
|
|
930
|
-
keyAddress: "0x90f79bf6eb2c4f870365e785982e1f101e93b906",
|
|
931
|
-
protocolVersion: "1",
|
|
932
|
-
nonce: "0x63ed6389bd2a1d23bb678583c227172bda874e82b97b1c170bfeeb4373b4b0d5",
|
|
933
|
-
sig: "0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001b"
|
|
934
|
-
}
|
|
935
|
-
}
|
|
936
|
-
]
|
|
937
|
-
},
|
|
938
1129
|
"auth.ok": {
|
|
939
1130
|
name: "auth.ok",
|
|
940
1131
|
title: "auth.ok (S2F)",
|
|
@@ -1077,11 +1268,11 @@ var asyncapi_default = {
|
|
|
1077
1268
|
payload: {
|
|
1078
1269
|
type: "error",
|
|
1079
1270
|
id: "g-5",
|
|
1080
|
-
sentAt:
|
|
1271
|
+
sentAt: 1789999980150,
|
|
1081
1272
|
sig: "0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001b",
|
|
1082
|
-
re: "
|
|
1273
|
+
re: "a-2",
|
|
1083
1274
|
code: "UNAUTHENTICATED",
|
|
1084
|
-
message: "
|
|
1275
|
+
message: "no live challenge of this fillerId with this nonce"
|
|
1085
1276
|
}
|
|
1086
1277
|
},
|
|
1087
1278
|
{
|
|
@@ -1097,6 +1288,20 @@ var asyncapi_default = {
|
|
|
1097
1288
|
reason: "REPAY_TO_BLOCKLISTED",
|
|
1098
1289
|
message: "repayTo is blocklisted by the input token"
|
|
1099
1290
|
}
|
|
1291
|
+
},
|
|
1292
|
+
{
|
|
1293
|
+
name: "errorS2F-4",
|
|
1294
|
+
payload: {
|
|
1295
|
+
type: "error",
|
|
1296
|
+
id: "g-18",
|
|
1297
|
+
fillerId: "acme-markets",
|
|
1298
|
+
sig: "0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001b",
|
|
1299
|
+
sentAt: 1789999991500,
|
|
1300
|
+
re: "q-2",
|
|
1301
|
+
code: "RATE_LIMITED",
|
|
1302
|
+
message: "quote rate class over its limit",
|
|
1303
|
+
retryAfterMs: 850
|
|
1304
|
+
}
|
|
1100
1305
|
}
|
|
1101
1306
|
]
|
|
1102
1307
|
},
|
|
@@ -1537,6 +1742,22 @@ var asyncapi_default = {
|
|
|
1537
1742
|
ticketSigHash: "0x9d30145c6e97cad96cf7cee181ac9d5b879dea7fed0730d7197e84e28487292b",
|
|
1538
1743
|
sig: "0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001b"
|
|
1539
1744
|
}
|
|
1745
|
+
},
|
|
1746
|
+
{
|
|
1747
|
+
name: "ticket-receipt-2",
|
|
1748
|
+
payload: {
|
|
1749
|
+
type: "ticket.receipt",
|
|
1750
|
+
id: "rc-2",
|
|
1751
|
+
fillerId: "acme-markets",
|
|
1752
|
+
sentAt: 1790000025e3,
|
|
1753
|
+
msgSig: "0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001b",
|
|
1754
|
+
form: "canton",
|
|
1755
|
+
orderHash: "0x585ec61a0813109803da9d47aea37a165f7df1371553f1e4ea8c139cf74058a6",
|
|
1756
|
+
attempt: 2,
|
|
1757
|
+
deliveryOrderCid: "00a1b2c3d4e5f6#fixture-delivery-order",
|
|
1758
|
+
validUntil: "1790000400",
|
|
1759
|
+
sig: "0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001b"
|
|
1760
|
+
}
|
|
1540
1761
|
}
|
|
1541
1762
|
]
|
|
1542
1763
|
},
|
|
@@ -1768,7 +1989,7 @@ var messages_schema_default = {
|
|
|
1768
1989
|
$schema: "https://json-schema.org/draft/2020-12/schema",
|
|
1769
1990
|
$id: "https://cancore.io/schemas/filler-protocol/v1/messages.schema.json",
|
|
1770
1991
|
title: "Cancore filler protocol v1 \u2014 WebSocket frames",
|
|
1771
|
-
$comment: "One $def per frame type, validated by name ($defs/<type>). The schemas encode the SENDER rule (protocol \xA73.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\u2192F types, and treat an unknown reason/result/code as OTHER/generic. Every enum is open: anyOf [known values, futureEnumValue]. x-direction: S2F = gateway to filler, F2S = filler to gateway, both = either way (ping, pong, error; <type>S2F is the gateway's copy, <type>F2S the filler's). Every frame in both directions carries id, sentAt and fillerId (
|
|
1992
|
+
$comment: "One $def per frame type, validated by name ($defs/<type>). The schemas encode the SENDER rule (protocol \xA73.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\u2192F types, and treat an unknown reason/result/code as OTHER/generic. Every enum is open: anyOf [known values, futureEnumValue]. x-direction: S2F = gateway to filler, F2S = filler to gateway, both = either way (ping, pong, error; <type>S2F is the gateway's copy, <type>F2S the filler's). x-rest-only: the type travels only as a REST body (auth.challenge, auth.response: the login of protocol \xA73.6), never on the WebSocket. Every frame in both directions carries id, sentAt and fillerId (optional only on a gateway error that refuses a login, POST /v1/filler/auth) and is signed (protocol \xA73.4): `sig` = the gateway key over GatewayMessage{bodyHash} on S2F, `msgSig` = the filler's message key over FillerMessage{bodyHash} on F2S, bodyHash = keccak256(JCS(frame without that field)). No exceptions: ticket.decline, a declining quote.reconfirm.reply, fill.reported, pong and error from the filler are signed too.",
|
|
1772
1993
|
$defs: {
|
|
1773
1994
|
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" },
|
|
1774
1995
|
uintDec256: { type: "string", pattern: "^(0|[1-9][0-9]*)$", maxLength: 78, description: "uint256 as a decimal string" },
|
|
@@ -1891,16 +2112,18 @@ var messages_schema_default = {
|
|
|
1891
2112
|
},
|
|
1892
2113
|
"auth.challenge": {
|
|
1893
2114
|
"x-direction": "S2F",
|
|
2115
|
+
"x-rest-only": true,
|
|
1894
2116
|
type: "object",
|
|
1895
|
-
description: "
|
|
1896
|
-
allOf: [{ $ref: "#/$defs/
|
|
2117
|
+
description: "The login challenge, addressed to the fillerId it was asked for: the 200 body of GET /v1/filler/auth/challenge?fillerId=. Never sent on the WebSocket. The filler checks the gateway sig and that fillerId is its own before it signs FillerAuth{fillerId, nonce, expiresAt}",
|
|
2118
|
+
allOf: [{ $ref: "#/$defs/s2fBase" }],
|
|
1897
2119
|
required: ["type", "nonce", "expiresAt"],
|
|
1898
2120
|
properties: { type: { const: "auth.challenge" }, nonce: { $ref: "#/$defs/bytes32" }, expiresAt: { $ref: "#/$defs/timeS" } }
|
|
1899
2121
|
},
|
|
1900
2122
|
"auth.response": {
|
|
1901
2123
|
"x-direction": "F2S",
|
|
1902
2124
|
type: "object",
|
|
1903
|
-
|
|
2125
|
+
"x-rest-only": true,
|
|
2126
|
+
description: "The body of POST /v1/filler/auth, answered with {token, expiresAt}. sig = FillerAuth{fillerId, nonce, expiresAt} by the registered message key of fillerId (keyAddress = its address); msgSig by the same key. Never sent on the WebSocket: a WebSocket connection is authenticated by the bearer token offered on the upgrade",
|
|
1904
2127
|
allOf: [{ $ref: "#/$defs/f2sBase" }],
|
|
1905
2128
|
required: ["type", "fillerId", "keyAddress", "protocolVersion", "sig"],
|
|
1906
2129
|
properties: {
|
|
@@ -1908,7 +2131,7 @@ var messages_schema_default = {
|
|
|
1908
2131
|
fillerId: { $ref: "#/$defs/fillerId" },
|
|
1909
2132
|
keyAddress: { $ref: "#/$defs/address" },
|
|
1910
2133
|
protocolVersion: { type: "string", description: 'the gateway answers UNSUPPORTED_VERSION to anything it does not serve; v1 senders send "1"' },
|
|
1911
|
-
nonce: { $ref: "#/$defs/bytes32", description: "
|
|
2134
|
+
nonce: { $ref: "#/$defs/bytes32", description: "the auth.challenge nonce this response answers (optional; senders SHOULD send it), so POST /v1/filler/auth finds the live challenge of this fillerId without trying every one" },
|
|
1912
2135
|
sig: { $ref: "#/$defs/sig65" }
|
|
1913
2136
|
}
|
|
1914
2137
|
},
|
|
@@ -1960,10 +2183,16 @@ var messages_schema_default = {
|
|
|
1960
2183
|
},
|
|
1961
2184
|
errorS2F: {
|
|
1962
2185
|
type: "object",
|
|
1963
|
-
description: "Reply to the F\u2192S frame `re`; also the REST error body. fillerId
|
|
2186
|
+
description: "Reply to the F\u2192S frame `re`; also the REST error body. fillerId may be absent on a refusal of POST /v1/filler/auth, which is not authenticated yet. reason names the failed pre-ticket check with TICKET_REFUSED. retryAfterMs comes with RATE_LIMITED only",
|
|
1964
2187
|
allOf: [{ $ref: "#/$defs/s2fEnvelope" }],
|
|
1965
2188
|
required: ["type", "code", "message"],
|
|
1966
|
-
properties: {
|
|
2189
|
+
properties: {
|
|
2190
|
+
type: { const: "error" },
|
|
2191
|
+
code: { $ref: "#/$defs/errorCode" },
|
|
2192
|
+
message: { type: "string" },
|
|
2193
|
+
reason: { $ref: "#/$defs/ticketRefusedReason" },
|
|
2194
|
+
retryAfterMs: { $ref: "#/$defs/durationMs", type: "integer", minimum: 1, description: "with RATE_LIMITED: ms (\u2265 1) until the rate class of the refused message holds a token again, or until the cooldown of the fillerId ends; the filler sends nothing of that class before it" }
|
|
2195
|
+
},
|
|
1967
2196
|
if: { type: "object", properties: { code: { const: "TICKET_REFUSED" } }, required: ["code"] },
|
|
1968
2197
|
then: { type: "object", required: ["reason"], properties: { reason: true } }
|
|
1969
2198
|
},
|
|
@@ -2161,17 +2390,26 @@ var messages_schema_default = {
|
|
|
2161
2390
|
"ticket.receipt": {
|
|
2162
2391
|
"x-direction": "F2S",
|
|
2163
2392
|
type: "object",
|
|
2164
|
-
description: "sig = TicketReceipt{ticketHash, ticketSigHash} by the message key
|
|
2165
|
-
|
|
2166
|
-
required: ["type", "orderHash", "attempt", "ticketHash", "ticketSigHash", "sig"],
|
|
2393
|
+
description: 'form follows the issued ticket (S-14). EVM form (form absent or "evm"): sig = TicketReceipt{ticketHash, ticketSigHash} by the message key. Canton form: sig = CantonTicketReceipt{orderHash, attempt, deliveryOrderCidHash = keccak256(utf8(deliveryOrderCid)), validUntil} by the message key, deliveryOrderCid and validUntil exactly as in ticket.issued; fillerId and repayTo are not part of it (protocol \xA73.3, \xA710 D-O)',
|
|
2394
|
+
required: ["type", "orderHash", "attempt", "sig"],
|
|
2167
2395
|
properties: {
|
|
2168
2396
|
type: { const: "ticket.receipt" },
|
|
2397
|
+
form: { anyOf: [{ enum: ["evm", "canton"] }, { type: "string", pattern: "^[a-z][a-z0-9-]*$" }] },
|
|
2169
2398
|
orderHash: { $ref: "#/$defs/bytes32" },
|
|
2170
2399
|
attempt: { $ref: "#/$defs/uint32" },
|
|
2171
|
-
ticketHash: { $ref: "#/$defs/bytes32" },
|
|
2172
|
-
ticketSigHash: { $ref: "#/$defs/bytes32" },
|
|
2173
2400
|
sig: { $ref: "#/$defs/sig65" }
|
|
2174
|
-
}
|
|
2401
|
+
},
|
|
2402
|
+
allOf: [
|
|
2403
|
+
{ $ref: "#/$defs/f2sBase" },
|
|
2404
|
+
{
|
|
2405
|
+
if: { type: "object", properties: { form: { const: "evm" } } },
|
|
2406
|
+
then: { type: "object", required: ["ticketHash", "ticketSigHash"], properties: { ticketHash: { $ref: "#/$defs/bytes32" }, ticketSigHash: { $ref: "#/$defs/bytes32" } } }
|
|
2407
|
+
},
|
|
2408
|
+
{
|
|
2409
|
+
if: { type: "object", properties: { form: { const: "canton" } }, required: ["form"] },
|
|
2410
|
+
then: { type: "object", required: ["deliveryOrderCid", "validUntil"], properties: { deliveryOrderCid: { type: "string", minLength: 1, description: "the contract id of the DeliveryOrder, exactly as ticket.issued sent it" }, validUntil: { $ref: "#/$defs/timeS", description: "= ticket.issued.validUntil" } } }
|
|
2411
|
+
}
|
|
2412
|
+
]
|
|
2175
2413
|
},
|
|
2176
2414
|
"fill.reported": {
|
|
2177
2415
|
"x-direction": "F2S",
|
|
@@ -2391,10 +2629,10 @@ var rest_schema_default = {
|
|
|
2391
2629
|
$schema: "https://json-schema.org/draft/2020-12/schema",
|
|
2392
2630
|
$id: "https://cancore.io/schemas/filler-protocol/v1/rest.schema.json",
|
|
2393
2631
|
title: "Cancore filler protocol v1 \u2014 REST fallback",
|
|
2394
|
-
$comment: "protocol \xA73.6. Bodies are the WebSocket frames: every request body is a filler message with its envelope (id, fillerId, sentAt) and msgSig, verified before processing as on the WebSocket (S-19); every response is a freshly signed S\u2192F message. /v1/filler
|
|
2632
|
+
$comment: "protocol \xA73.6. Bodies are the WebSocket frames: every request body is a filler message with its envelope (id, fillerId, sentAt) and msgSig, verified before processing as on the WebSocket (S-19); every response is a freshly signed S\u2192F message. Login: GET /v1/filler/auth/challenge?fillerId= returns a signed auth.challenge addressed to that fillerId; POST /v1/filler/auth with the auth.response (FillerAuth over it) returns {token, expiresAt}. The challenge route is anonymous and its refusals are UNSIGNED (unsignedErrorBody, no sig, nothing journalled): 400 BAD_REQUEST \u2014 fillerId missing or not a fillerId; 404 UNKNOWN_REQUEST \u2014 fillerId unknown or not ACTIVE; the anonymous login steps are charged to no fillerId's rate limits (knowing a fillerId cannot lock its filler out); a 429 here comes only from the per-IP limit in front of filler-gateway. POST /v1/filler/auth refuses UNSIGNED too as long as it has checked no signature: 400 BAD_REQUEST \u2014 no or a malformed fillerId; 404 UNKNOWN_REQUEST \u2014 fillerId unknown or not ACTIVE; 401 UNAUTHENTICATED \u2014 the fillerId holds no live challenge (evicted, expired or used: ask for a new one). Its refusals after the signature checks (BAD_SIGNATURE, STALE_MESSAGE, REPLAYED_MESSAGE, UNSUPPORTED_VERSION, NOT_ELIGIBLE, UNAUTHENTICATED) are the signed error. The other /v1/filler/* routes need `Authorization: Bearer <token>`; the token is bound to (fillerId, message key) and stops working when it expires, when the message key is changed, or when the filler is no longer ACTIVE. The same token opens the WebSocket (asyncapi.json: offered as the subprotocol bearer.<token>). A ticket of another filler is 404 UNKNOWN_TICKET. Rate limits are per fillerId, shared by REST and every WebSocket session of it: over the limit a bearer route answers 429 with an UNSIGNED unsignedErrorBody {type: error, code: RATE_LIMITED, message, retryAfterMs} and a Retry-After header (seconds, rounded up), journals nothing one by one, and the request changes nothing; during the cooldown after sustained excess every bearer route answers so. Every 429 is unsigned, on every route; a filler decides by the status and takes retryAfterMs (else Retry-After) as a hint. Every other non-2xx of a bearer route is the signed error. GET /v1/filler/attestations/{orderHash} answers 404 ATTESTATIONS_NOT_READY until the gateway holds \u2265 threshold verified signatures for this filler's fill, and 404 UNKNOWN_TICKET when this filler holds no ticket on the order. /v1/draws/* and /v1/gateway are public. Every non-2xx body is the signed `error` frame, with the HTTP status of x-error-status \u2014 except a 429 (always unsignedErrorBody) and the unsigned refusals of an endpoint that names an errorBody. x-endpoints: request/query/response/errorBody name a $def here or in messages.schema.json.",
|
|
2395
2633
|
"x-endpoints": [
|
|
2396
|
-
{ method: "GET", path: "/v1/filler/auth/challenge", auth: "none", response: "messages.schema.json#/$defs/auth.challenge" },
|
|
2397
|
-
{ method: "POST", path: "/v1/filler/auth", auth: "none", request: "messages.schema.json#/$defs/auth.response", response: "#/$defs/authToken" },
|
|
2634
|
+
{ method: "GET", path: "/v1/filler/auth/challenge", auth: "none", query: "#/$defs/challengeQuery", response: "messages.schema.json#/$defs/auth.challenge", errorBody: "#/$defs/unsignedErrorBody" },
|
|
2635
|
+
{ method: "POST", path: "/v1/filler/auth", auth: "none", request: "messages.schema.json#/$defs/auth.response", response: "#/$defs/authToken", errorBody: "#/$defs/unsignedErrorBody" },
|
|
2398
2636
|
{ method: "GET", path: "/v1/filler/tickets", auth: "bearer", query: "#/$defs/ticketListQuery", response: "#/$defs/ticketList" },
|
|
2399
2637
|
{ 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" },
|
|
2400
2638
|
{ method: "POST", path: "/v1/filler/tickets/{orderHash}/{attempt}/receipt", auth: "bearer", request: "messages.schema.json#/$defs/ticket.receipt", response: "#/$defs/empty" },
|
|
@@ -2427,6 +2665,22 @@ var rest_schema_default = {
|
|
|
2427
2665
|
},
|
|
2428
2666
|
$defs: {
|
|
2429
2667
|
errorBody: { $ref: "messages.schema.json#/$defs/errorS2F" },
|
|
2668
|
+
unsignedErrorBody: {
|
|
2669
|
+
type: "object",
|
|
2670
|
+
description: "An unsigned refusal: every 429, and the refusals of the login routes decided before any signature check. Not signed, not addressed, nothing journalled; a filler cannot verify it and treats it as a hint only (status, code, retryAfterMs)",
|
|
2671
|
+
required: ["type", "code", "message"],
|
|
2672
|
+
properties: {
|
|
2673
|
+
type: { const: "error" },
|
|
2674
|
+
code: { $ref: "messages.schema.json#/$defs/errorCode" },
|
|
2675
|
+
message: { type: "string" },
|
|
2676
|
+
retryAfterMs: { $ref: "messages.schema.json#/$defs/durationMs", type: "integer", minimum: 1, description: "with RATE_LIMITED (429): ms until the rate class may be used again" }
|
|
2677
|
+
}
|
|
2678
|
+
},
|
|
2679
|
+
challengeQuery: {
|
|
2680
|
+
type: "object",
|
|
2681
|
+
required: ["fillerId"],
|
|
2682
|
+
properties: { fillerId: { $ref: "messages.schema.json#/$defs/fillerId", description: "the filler logging in; the challenge is addressed to it and answerable only by it" } }
|
|
2683
|
+
},
|
|
2430
2684
|
empty: { type: "object", description: "no fields in v1; receivers ignore unknown ones (V-2)" },
|
|
2431
2685
|
authToken: {
|
|
2432
2686
|
type: "object",
|
|
@@ -2521,10 +2775,11 @@ var rest_schema_default = {
|
|
|
2521
2775
|
// src/protocol/schemas.ts
|
|
2522
2776
|
var PROTOCOL_SCHEMAS = { messages: messages_schema_default, rest: rest_schema_default, records: records_schema_default };
|
|
2523
2777
|
var ASYNCAPI = asyncapi_default;
|
|
2524
|
-
var SCHEMA_VOCABULARY = ["x-direction", "x-endpoints", "x-error-status"];
|
|
2778
|
+
var SCHEMA_VOCABULARY = ["x-direction", "x-rest-only", "x-endpoints", "x-error-status"];
|
|
2525
2779
|
var MESSAGE_DIRECTIONS = Object.fromEntries(
|
|
2526
2780
|
Object.entries(messages_schema_default.$defs).filter(([, def]) => def["x-direction"]).map(([type, def]) => [type, def["x-direction"]])
|
|
2527
2781
|
);
|
|
2782
|
+
var REST_ONLY_TYPES = Object.entries(messages_schema_default.$defs).filter(([, def]) => def["x-rest-only"] === true).map(([type]) => type);
|
|
2528
2783
|
var REST_ENDPOINTS = rest_schema_default["x-endpoints"];
|
|
2529
2784
|
function messageSchemaRef(type, direction) {
|
|
2530
2785
|
const def = direction && MESSAGE_DIRECTIONS[type] === "both" ? `${type}${direction}` : type;
|
|
@@ -2680,6 +2935,6 @@ function describeRevert(selectorOrData, tables) {
|
|
|
2680
2935
|
return void 0;
|
|
2681
2936
|
}
|
|
2682
2937
|
|
|
2683
|
-
export { ASYNCAPI, BUILD_HASHES, BYTECODE_HASHES, CONTRACTS_RELEASE, DECLINE_REASONS, DEPLOYMENTS, DRAND_QUICKNET, DRAW_CLOSED_BY, ERROR_CODES, ERROR_HTTP_STATUS, EXEMPT_REASONS, EXPIRED_RESULTS, FEE_CLAIM_DOMAIN_NAME, FEE_CLAIM_DOMAIN_VERSION, FEE_CLAIM_TYPES, FILLER_AUTH_TYPES, FILLER_GATEWAYS, FILLER_ID_PATTERN, FILLER_KEY_REGISTRATION_TYPES, FILLER_MESSAGE_TYPES, FILLER_PROTOCOL_DOMAIN, FILLER_QUOTE_TYPES, FILL_PROOF_DOMAIN, FILL_PROOF_TYPES, FILL_PROOF_TYPE_STRING, FILL_TICKET_DOMAIN, FILL_TICKET_TYPES, GATEWAY_MESSAGE_TYPES, MESSAGE_DIRECTIONS, ORDER_TYPES, PENALTY_STEPS, PERMIT2_ADDRESS, PROOF_KIND_ATTESTATION, PROTOCOL_SCHEMAS, PROTOCOL_VERSION, QUOTE_ACK_STATUSES, QUOTE_FINAL_STATUSES, QUOTE_TYPES, REST_ENDPOINTS, SCHEMA_VOCABULARY, STAKE_BINDING_TYPES, TICKET_INTENT_TYPES, TICKET_LIST_STATUSES, TICKET_RECEIPT_TYPES, TICKET_REFUSED_REASONS, cantonSigEntries, deploymentOf, describeRevert, drawValue, drawWinner, encodeType, evmAddressFromRepayTo, feeClaimDomain, fillProofDomain, fillerEnvelopeError, fillerIdHash, fillerMessageBodyHash, firstRoundAtOrAfter, gatewayBodyHash, hashDomain, hashFillProof, hashFillTicket, hashFillerKeyRegistration, hashFillerMessage, hashFillerQuote, hashStruct, hashTicketIntent, hashTypedData, isCantonSource, isEoaSignature, isEvmRepayTo, jcs, messageIdRetainUntil, messageSchemaRef, repayToFromEvm, repayToFromParty, requestIdHash, routerDomain, settleAttestationsErrors, settleAttestationsPayload, settleAttestationsPayloadHash, settleSigs, typeHash };
|
|
2938
|
+
export { ASYNCAPI, BPS, BUILD_HASHES, BYTECODE_HASHES, CANTON_ORIGIN_ID, CANTON_SOURCE_ANCHOR, CANTON_TICKET_RECEIPT_TYPES, CONTRACTS_RELEASE, DAML_NUMERIC_SCALE, DECLINE_REASONS, DEPLOYMENTS, DRAND_QUICKNET, DRAW_CLOSED_BY, EIP2294_MAX_CHAIN_ID, ERROR_CODES, ERROR_HTTP_STATUS, EXEMPT_REASONS, EXPIRED_RESULTS, FEE_CLAIM_DOMAIN_NAME, FEE_CLAIM_DOMAIN_VERSION, FEE_CLAIM_TYPES, FILLER_AUTH_TYPES, FILLER_CLOSE_CODES, FILLER_GATEWAYS, FILLER_ID_PATTERN, FILLER_KEY_REGISTRATION_TYPES, FILLER_MESSAGE_TYPES, FILLER_PROTOCOL_DOMAIN, FILLER_QUOTE_TYPES, FILLER_UPGRADE_REFUSALS, FILLER_WS_BEARER_PREFIX, FILLER_WS_SUBPROTOCOL, FILL_PROOF_DOMAIN, FILL_PROOF_TYPES, FILL_PROOF_TYPE_STRING, FILL_TICKET_DOMAIN, FILL_TICKET_TYPES, GATEWAY_MESSAGE_TYPES, GRACE, INSTRUMENT_LABEL_TAG, MAX_FEE_BPS, MAX_FILL_TTL, MAX_PROOF_WINDOW, MAX_SIG_TTL, MESSAGE_DIRECTIONS, MIN_FILL_TTL, ORDER_TYPES, OWNER_LABEL_TAG, PENALTY_STEPS, PERMIT2_ADDRESS, PERMIT2_WITNESS_TYPE_STRING, PERMIT_WITNESS_TYPES, PROOF_KIND_ATTESTATION, PROTOCOL_SCHEMAS, PROTOCOL_VERSION, QUOTE_ACK_STATUSES, QUOTE_FINAL_STATUSES, QUOTE_TYPES, REST_ENDPOINTS, REST_ONLY_TYPES, SCHEMA_VOCABULARY, SET_DELAY, STAKE_BINDING_TYPES, TICKET_INTENT_TYPES, TICKET_LIST_STATUSES, TICKET_RECEIPT_TYPES, TICKET_REFUSED_REASONS, buildCantonSourceOrder, cantonInclusiveFeeSplit, cantonNetworkOfDestination, cantonSigEntries, cantonTicketReceipt, deliveryOrderCidHash, deploymentOf, describeRevert, drawValue, drawWinner, encodeCantonAmount, encodeCantonDestination, encodeCantonOutputAsset, encodeCantonRecipient, encodeType, evmAddressFromRepayTo, feeClaimDomain, fillProofDomain, fillerEnvelopeError, fillerIdHash, fillerMessageBodyHash, fillerWsProtocols, firstRoundAtOrAfter, gatewayBodyHash, hashCantonTicketReceipt, hashDomain, hashFillProof, hashFillTicket, hashFillerKeyRegistration, hashFillerMessage, hashFillerQuote, hashOrder, hashPermitWitness, hashStruct, hashTicketIntent, hashTypedData, inclusiveFeeSplit, isCantonOriginId, isCantonSource, isEoaSignature, isEvmRepayTo, jcs, messageIdRetainUntil, messageSchemaRef, permit2Domain, repayToFromEvm, repayToFromParty, requestIdHash, routerDomain, settleAttestationsErrors, settleAttestationsPayload, settleAttestationsPayloadHash, settleSigs, sourceOrderHash, typeHash };
|
|
2684
2939
|
//# sourceMappingURL=index.js.map
|
|
2685
2940
|
//# sourceMappingURL=index.js.map
|