@cancore/contracts 0.2.0-rc.6 → 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/dist/index.d.ts CHANGED
@@ -160,6 +160,49 @@ declare function fillProofDomain(chainId: number | bigint, verifyingContract: `0
160
160
  */
161
161
  declare function hashFillProof(proof: FillProof, chainId: number | bigint, verifyingContract: `0x${string}`): `0x${string}`;
162
162
 
163
+ /**
164
+ * The constants of the intent rail: the router's public constants (held to the
165
+ * contract by `spec/constants.json`, which `npm run sync` reads out of the
166
+ * Solidity source — SDK-6) and the constants of the Canton-source encoding
167
+ * (held to `spec/vectors/canton-order.json`, protocol.md §3.8).
168
+ * `PROOF_KIND_ATTESTATION` lives in `./eip712`, next to `FillProof`.
169
+ */
170
+ /** `CancoreRouter.BPS`: basis points in one whole. */
171
+ declare const BPS = 10000;
172
+ /** `CancoreRouter.MAX_FEE_BPS`: the highest `Order.feeBps` `openFor` accepts — 10 % on top of the net, 1/11 of the total. */
173
+ declare const MAX_FEE_BPS = 1000;
174
+ /** `CancoreRouter.MIN_FILL_TTL`, seconds: `openFor` needs `fillDeadline ≥ now + MIN_FILL_TTL`. */
175
+ declare const MIN_FILL_TTL = 60;
176
+ /** `AttestorSet.MAX_FILL_TTL`, seconds (24 h): `openFor` needs `fillDeadline ≤ now + MAX_FILL_TTL`. */
177
+ declare const MAX_FILL_TTL = 86400;
178
+ /** `AttestorSet.MAX_SIG_TTL`, seconds (24 h): `openFor` needs `createdAt ≤ now ≤ createdAt + MAX_SIG_TTL`. */
179
+ declare const MAX_SIG_TTL = 86400;
180
+ /** `AttestorSet.MAX_PROOF_WINDOW`, seconds (4 h): the cap of `proofWindow`, so `refundAfter ≤ fillDeadline + MAX_PROOF_WINDOW`. */
181
+ declare const MAX_PROOF_WINDOW = 14400;
182
+ /** `AttestorSet.GRACE`, seconds (28 h): the longest intent lifetime; a replaced attestor set keeps verifying this long. */
183
+ declare const GRACE: number;
184
+ /** `AttestorSet.SET_DELAY`, seconds (72 h): a proposed attestor set activates this late; above `MAX_SIG_TTL + GRACE`. */
185
+ declare const SET_DELAY = 259200;
186
+ /** ⌊(2⁶⁴ − 1) / 2⌋ − 36, the largest EVM chain id EIP-2294 allows: every Canton origin id is above it. */
187
+ declare const EIP2294_MAX_CHAIN_ID = 9223372036854775771n;
188
+ /** `Order.originChainId` of a Canton-source order, per Canton network: 2⁶³ + n (2⁶³ itself is unassigned). */
189
+ declare const CANTON_ORIGIN_ID: {
190
+ readonly mainnet: 9223372036854775809n;
191
+ readonly testnet: 9223372036854775810n;
192
+ readonly devnet: 9223372036854775811n;
193
+ };
194
+ /**
195
+ * `verifyingContract` of the Canton source domain, one for every Canton network:
196
+ * `address(uint160(uint256(keccak256("cancore:canton-source-anchor:v1"))))`, an address no router can be deployed at.
197
+ */
198
+ declare const CANTON_SOURCE_ANCHOR: "0x2f37b46Ea93001829498b145985fb53028033701";
199
+ /** Domain-separation tag of the owner label (`Order.user` of a Canton-source order). */
200
+ declare const OWNER_LABEL_TAG = "cancore:owner:v1";
201
+ /** Domain-separation tag of the instrument label (`Order.inputToken` of a Canton-source order). */
202
+ declare const INSTRUMENT_LABEL_TAG = "cancore:instrument:v1";
203
+ /** Daml `Numeric 10`: Canton amounts are exact at 10⁻¹⁰, and their EVM form is the amount × 10¹⁰. */
204
+ declare const DAML_NUMERIC_SCALE = 10;
205
+
163
206
  /**
164
207
  * The EIP-712 types and domains of the Cancore intent rail, filler protocol v1.
165
208
  *
@@ -327,6 +370,26 @@ declare const TICKET_RECEIPT_TYPES: {
327
370
  readonly type: "bytes32";
328
371
  }];
329
372
  };
373
+ /**
374
+ * `CantonTicketReceipt(bytes32 orderHash,uint32 attempt,bytes32 deliveryOrderCidHash,uint64 validUntil)` — the receipt of a
375
+ * Canton-form ticket, which has no `FillTicket` and no `ticketSig`; signed by the message key. `fillerId` and `repayTo`
376
+ * are not in it: they travel in `ticket.issued` (protocol.md §3.3, §10 D-O).
377
+ */
378
+ declare const CANTON_TICKET_RECEIPT_TYPES: {
379
+ readonly CantonTicketReceipt: readonly [{
380
+ readonly name: "orderHash";
381
+ readonly type: "bytes32";
382
+ }, {
383
+ readonly name: "attempt";
384
+ readonly type: "uint32";
385
+ }, {
386
+ readonly name: "deliveryOrderCidHash";
387
+ readonly type: "bytes32";
388
+ }, {
389
+ readonly name: "validUntil";
390
+ readonly type: "uint64";
391
+ }];
392
+ };
330
393
  /** `StakeBinding(string partnerId,address stakingAddress,uint256 chainId,uint64 nonce)` — signed by the staking address. */
331
394
  declare const STAKE_BINDING_TYPES: {
332
395
  readonly StakeBinding: readonly [{
@@ -441,6 +504,14 @@ interface TicketReceipt {
441
504
  /** keccak256 of the 65 raw signature bytes. */
442
505
  ticketSigHash: Hex;
443
506
  }
507
+ interface CantonTicketReceipt {
508
+ orderHash: Hex;
509
+ attempt: number;
510
+ /** `deliveryOrderCidHash(deliveryOrderCid)`: keccak256 of the contract id exactly as `ticket.issued` sent it. */
511
+ deliveryOrderCidHash: Hex;
512
+ /** `ticket.issued.validUntil` (= `DeliveryOrder.validUntil`), unix seconds. */
513
+ validUntil: UintLike;
514
+ }
444
515
  interface StakeBinding {
445
516
  partnerId: string;
446
517
  stakingAddress: Hex;
@@ -466,6 +537,198 @@ interface FillerKeyRegistration {
466
537
  issuedAt: UintLike;
467
538
  }
468
539
 
540
+ /** The source-router domain an order is hashed in: its chain id and router (Canton: `CANTON_ORIGIN_ID`, `CANTON_SOURCE_ANCHOR`). */
541
+ interface OrderDomain {
542
+ chainId: UintLike;
543
+ verifyingContract: Hex | string;
544
+ }
545
+ /** `CancoreRouter.hashOrder`: the EIP-712 digest of `order` in the router domain `{chainId, verifyingContract}` — the `orderHash`. */
546
+ declare function hashOrder(order: Order, domain: OrderDomain): Hex;
547
+ /** Whether `chainId` is the `Order.originChainId` of a Canton network (`CANTON_ORIGIN_ID`). */
548
+ declare function isCantonOriginId(chainId: UintLike): boolean;
549
+ /**
550
+ * `CancoreRouter.sourceOrderHash`: the order hash as its SOURCE router computed it — what a destination
551
+ * keys `filled` on. A Canton origin hashes under `CANTON_SOURCE_ANCHOR`; an EVM origin needs the source
552
+ * router registered for it (`sourceRouter[originChainId]`), and is refused without one as the router
553
+ * reverts `SourceRouterUnknown`.
554
+ */
555
+ declare function sourceOrderHash(order: Order, sourceRouter?: Hex | string): Hex;
556
+ /** A Canton-source intent as its owner signs it (`SwapIntentRequest`), the input of `buildCantonSourceOrder`. */
557
+ interface CantonSourceIntent {
558
+ /** Canton party id of the owner, e.g. `alice::1220abc…`. */
559
+ ownerPartyId: string;
560
+ /** `requestId` of the signed request; without it two identical requests would share a hash. */
561
+ requestId: string;
562
+ /** Party id of the instrument admin (registry operator). */
563
+ instrumentAdmin: string;
564
+ /** Instrument id inside that registry, e.g. `CNRX`. */
565
+ instrumentId: string;
566
+ /** Amount given (the total T, fee included), a Daml decimal string, at most 10 decimal places. */
567
+ amount: string;
568
+ /** EVM chain the output is delivered on. */
569
+ destinationChainId: UintLike;
570
+ /** ERC-20 delivered there. */
571
+ wantToken: string;
572
+ /** Its `decimals()`. */
573
+ wantDecimals: number;
574
+ /** Lower bound of the delivery, a decimal string in `wantToken` units. */
575
+ minReceived: string;
576
+ /** Receiver on the destination, an EVM address. */
577
+ recipient: string;
578
+ /** The owner-signed `orderCreatedAt` of the request (not the ledger time of Execute), unix seconds, a whole second. */
579
+ createdAt: number | string;
580
+ /** Unix seconds, a whole second. */
581
+ fillDeadline: number | string;
582
+ /** Inclusive fee rate as a decimal string, e.g. `"0.003"`; at most 4 decimal places, at most `MAX_FEE_BPS / 10 000`. */
583
+ feeRate: string;
584
+ /** One of `CANTON_ORIGIN_ID`. */
585
+ cantonOriginId: UintLike;
586
+ }
587
+ interface CantonSourceOrder {
588
+ /** The EVM-form `Order`: wide integers as decimal strings, addresses EIP-55, words lowercase. */
589
+ order: Order;
590
+ /** The Canton source domain: `CancoreRouter` v1, `CANTON_ORIGIN_ID`, `CANTON_SOURCE_ANCHOR`. */
591
+ domain: {
592
+ name: 'CancoreRouter';
593
+ version: '1';
594
+ chainId: string;
595
+ verifyingContract: typeof CANTON_SOURCE_ANCHOR;
596
+ };
597
+ orderHash: Hex;
598
+ }
599
+ /**
600
+ * The EVM-form `Order` of a Canton-source intent and its source-domain hash (protocol.md §3.7).
601
+ * Refuses rather than rounds: an amount, a fee or a time the chain cannot represent exactly is
602
+ * rejected BEFORE the owner signs, because after that the `orderHash` is fixed.
603
+ */
604
+ declare function buildCantonSourceOrder(intent: CantonSourceIntent): CantonSourceOrder;
605
+ /**
606
+ * `CancoreRouter.WITNESS_TYPE_STRING`: the tail Permit2 appends after
607
+ * `"PermitWitnessTransferFrom(TokenPermissions permitted,address spender,uint256 nonce,uint256 deadline,"`.
608
+ */
609
+ declare const PERMIT2_WITNESS_TYPE_STRING: string;
610
+ /** The Permit2 witness typed data a wallet renders and signs (`eth_signTypedData_v4` types), the `Order` nested as `witness`. */
611
+ declare const PERMIT_WITNESS_TYPES: {
612
+ readonly Order: readonly [{
613
+ readonly name: "user";
614
+ readonly type: "address";
615
+ }, {
616
+ readonly name: "originChainId";
617
+ readonly type: "uint64";
618
+ }, {
619
+ readonly name: "inputToken";
620
+ readonly type: "address";
621
+ }, {
622
+ readonly name: "inputAmount";
623
+ readonly type: "uint256";
624
+ }, {
625
+ readonly name: "destination";
626
+ readonly type: "bytes32";
627
+ }, {
628
+ readonly name: "outputAsset";
629
+ readonly type: "bytes32";
630
+ }, {
631
+ readonly name: "minReceived";
632
+ readonly type: "uint256";
633
+ }, {
634
+ readonly name: "recipient";
635
+ readonly type: "bytes32";
636
+ }, {
637
+ readonly name: "createdAt";
638
+ readonly type: "uint64";
639
+ }, {
640
+ readonly name: "fillDeadline";
641
+ readonly type: "uint64";
642
+ }, {
643
+ readonly name: "feeBps";
644
+ readonly type: "uint16";
645
+ }];
646
+ readonly TokenPermissions: readonly [{
647
+ readonly name: "token";
648
+ readonly type: "address";
649
+ }, {
650
+ readonly name: "amount";
651
+ readonly type: "uint256";
652
+ }];
653
+ readonly PermitWitnessTransferFrom: readonly [{
654
+ readonly name: "permitted";
655
+ readonly type: "TokenPermissions";
656
+ }, {
657
+ readonly name: "spender";
658
+ readonly type: "address";
659
+ }, {
660
+ readonly name: "nonce";
661
+ readonly type: "uint256";
662
+ }, {
663
+ readonly name: "deadline";
664
+ readonly type: "uint256";
665
+ }, {
666
+ readonly name: "witness";
667
+ readonly type: "Order";
668
+ }];
669
+ };
670
+ /** The message of `PERMIT_WITNESS_TYPES`: `spender` is the source router, `permitted` the order's input token and amount. */
671
+ interface PermitWitness {
672
+ permitted: {
673
+ token: Hex | string;
674
+ amount: UintLike;
675
+ };
676
+ spender: Hex | string;
677
+ nonce: UintLike;
678
+ deadline: UintLike;
679
+ witness: Order;
680
+ }
681
+ /** The Permit2 domain: `{name: "Permit2", chainId, verifyingContract}` — no version. */
682
+ declare function permit2Domain(chainId: UintLike, permit2?: Hex | string): {
683
+ readonly name: "Permit2";
684
+ readonly chainId: UintLike;
685
+ readonly verifyingContract: string;
686
+ };
687
+ /** The digest the maker signs for `openFor`: `PermitWitnessTransferFrom` with the order as witness, in the Permit2 domain. */
688
+ declare function hashPermitWitness(permit: PermitWitness, chainId: UintLike, permit2?: Hex | string): Hex;
689
+
690
+ interface FeeSplit {
691
+ /** What the filler is paid. */
692
+ payout: bigint;
693
+ /** What Cancore keeps: `total − payout`. */
694
+ fee: bigint;
695
+ }
696
+ /**
697
+ * EVM source, `CancoreRouter.settle`: `payout = ⌊T × 10 000 / (10 000 + feeBps)⌋`, `fee = T − payout`.
698
+ * The rounding dust goes to the fee; a total below one net unit (`T × 10 000 < 10 000 + feeBps`)
699
+ * pays 0 and is all fee.
700
+ */
701
+ declare function inclusiveFeeSplit(total: UintLike, feeBps: UintLike): FeeSplit;
702
+ /**
703
+ * Canton source, Daml `inclusiveFee amount feeRate = amount − amount / (1.0 + feeRate)` in EVM-form
704
+ * units: the same quotient rounded half to even (Daml `Numeric 10` division), so the payout is the
705
+ * EVM one or one unit more. A filler prices a Canton-source order on this, never on the EVM formula (T-12).
706
+ */
707
+ declare function cantonInclusiveFeeSplit(total: UintLike, feeBps: UintLike): FeeSplit;
708
+
709
+ /** A Canton network, as in its CAIP-2 id `canton:<network>`. */
710
+ type CantonNetwork = keyof typeof CANTON_ORIGIN_ID;
711
+ /** `Order.destination` and `FillProof.destination` of a Canton network: `keccak256(utf8("canton:<network>"))`. */
712
+ declare function encodeCantonDestination(network: CantonNetwork): Hex;
713
+ /** The Canton network an order's `destination` names, or `undefined` when it is not a Canton destination. */
714
+ declare function cantonNetworkOfDestination(destination: string): CantonNetwork | undefined;
715
+ /**
716
+ * `Order.outputAsset` and `FillProof.outputAsset` of a Canton instrument:
717
+ * `keccak256(abi.encode("cancore:instrument:v1", admin, id))`, the full 32 bytes — the same hash a
718
+ * Canton-source `inputToken` label truncates to 20 bytes.
719
+ */
720
+ declare function encodeCantonOutputAsset(instrument: {
721
+ admin: string;
722
+ id: string;
723
+ }): Hex;
724
+ /** `Order.recipient` and `FillProof.recipient` of a Canton party: `keccak256(utf8(partyId))` over the full party id. */
725
+ declare function encodeCantonRecipient(partyId: string): Hex;
726
+ /**
727
+ * `Order.minReceived` and `FillProof.amountDelivered` of a Canton amount: the Daml `Numeric 10`
728
+ * decimal × 10¹⁰. No rounding: an amount that is not exact at 10⁻¹⁰ is refused before anyone signs.
729
+ */
730
+ declare function encodeCantonAmount(amount: string): bigint;
731
+
469
732
  interface TypedField {
470
733
  readonly name: string;
471
734
  readonly type: string;
@@ -536,17 +799,6 @@ declare function evmAddressFromRepayTo(repayTo: string): Hex;
536
799
  */
537
800
  declare function isEoaSignature(sig: unknown): sig is Hex;
538
801
 
539
- /** `hashTicket` of the router: the `FillTicket` digest in the ticket domain, the same on every chain. */
540
- declare const hashFillTicket: (ticket: FillTicket) => Hex;
541
- /** The `FillerQuote` digest; `quote.requestId` is already `requestIdHash(requestId)`. */
542
- declare const hashFillerQuote: (quote: FillerQuote) => Hex;
543
- /** The `TicketIntent` digest — the inner `sig` of `ticket.intent`. */
544
- declare const hashTicketIntent: (intent: TicketIntent) => Hex;
545
- /** What `msgSig` of a filler → filler-gateway message is over: `FillerMessage{bodyHash}` of the message without `msgSig`. */
546
- declare const hashFillerMessage: (message: object) => Hex;
547
- /** The `FillerKeyRegistration` digest; the registered key signs it, and it must recover to `messageKey`. */
548
- declare const hashFillerKeyRegistration: (registration: FillerKeyRegistration) => Hex;
549
-
550
802
  /**
551
803
  * `FillProof` on the wire (§3.1), field for field the struct the source router
552
804
  * hashes (`FILL_PROOF_TYPES`, the twelve variant A fields of protocol §3.3).
@@ -695,7 +947,7 @@ interface OrderJson {
695
947
  interface S2FBase {
696
948
  type: string;
697
949
  id: string;
698
- /** The addressee. Absent only on `auth.challenge` and on pre-auth `error`. */
950
+ /** The addressee. Absent only on an `error` that refuses a login (`POST /v1/filler/auth`). */
699
951
  fillerId?: string;
700
952
  sentAt: TimeMs;
701
953
  sig: Hex;
@@ -718,17 +970,23 @@ interface F2SEnvelope {
718
970
  interface F2SBase extends F2SEnvelope {
719
971
  type: string;
720
972
  }
973
+ /**
974
+ * The login challenge: the body of `GET /v1/filler/auth/challenge?fillerId=`, addressed to that
975
+ * `fillerId`. REST only — never on the WebSocket.
976
+ */
721
977
  interface AuthChallenge extends S2FBase {
722
978
  type: 'auth.challenge';
979
+ fillerId: string;
723
980
  nonce: Hex;
724
981
  expiresAt: DecString;
725
982
  }
983
+ /** The body of `POST /v1/filler/auth` (→ `AuthToken`). REST only — never on the WebSocket. */
726
984
  interface AuthResponse extends F2SBase {
727
985
  type: 'auth.response';
728
986
  fillerId: string;
729
987
  keyAddress: Hex;
730
988
  protocolVersion: '1';
731
- /** Optional: the `auth.challenge` nonce this answers, so the REST login finds its challenge directly. */
989
+ /** The `auth.challenge` nonce this answers (optional; senders should send it), so the login finds its challenge directly. */
732
990
  nonce?: Hex;
733
991
  sig: Hex;
734
992
  }
@@ -762,6 +1020,20 @@ interface ErrorMessage extends S2FBase {
762
1020
  code: ErrorCode;
763
1021
  message: string;
764
1022
  reason?: TicketRefusedReason;
1023
+ /** With `RATE_LIMITED`: ms (≥ 1) until the refused rate class may be used again, or until the cooldown ends. */
1024
+ retryAfterMs?: number;
1025
+ }
1026
+ /**
1027
+ * An unsigned, unaddressed refusal, so a filler cannot verify it; a hint only. Every 429 (`RATE_LIMITED`,
1028
+ * on every route), and the refusals of the login routes decided before any signature check:
1029
+ * 400 `BAD_REQUEST`, 404 `UNKNOWN_REQUEST`, and on `POST /v1/filler/auth` 401 `UNAUTHENTICATED`
1030
+ * (no live challenge for the fillerId: ask for a new one).
1031
+ */
1032
+ interface UnsignedErrorBody {
1033
+ type: 'error';
1034
+ code: ErrorCode;
1035
+ message: string;
1036
+ retryAfterMs?: number;
765
1037
  }
766
1038
  /** The filler's reply to a gateway frame it cannot handle; informational. */
767
1039
  interface ErrorF2S extends F2SBase {
@@ -895,14 +1167,27 @@ interface TicketIssuedCanton extends S2FBase {
895
1167
  repayTo: Hex;
896
1168
  }
897
1169
  type TicketIssued = TicketIssuedEvm | TicketIssuedCanton;
898
- interface TicketReceiptMessage extends F2SBase {
1170
+ /** EVM-form receipt (`form` absent or `"evm"`): `sig` = `TicketReceipt{ticketHash, ticketSigHash}` by the message key. */
1171
+ interface TicketReceiptEvm extends F2SBase {
899
1172
  type: 'ticket.receipt';
1173
+ form?: 'evm';
900
1174
  orderHash: Hex;
901
1175
  attempt: number;
902
1176
  ticketHash: Hex;
903
1177
  ticketSigHash: Hex;
904
1178
  sig: Hex;
905
1179
  }
1180
+ /** Canton-form receipt: `sig` = `CantonTicketReceipt` (`cantonTicketReceipt(frame)`) by the message key; fields as in `ticket.issued`. */
1181
+ interface TicketReceiptCanton extends F2SBase {
1182
+ type: 'ticket.receipt';
1183
+ form: 'canton';
1184
+ orderHash: Hex;
1185
+ attempt: number;
1186
+ deliveryOrderCid: string;
1187
+ validUntil: DecString;
1188
+ sig: Hex;
1189
+ }
1190
+ type TicketReceiptMessage = TicketReceiptEvm | TicketReceiptCanton;
906
1191
  interface FillReported extends F2SBase {
907
1192
  type: 'fill.reported';
908
1193
  orderHash: Hex;
@@ -933,10 +1218,15 @@ interface PenaltyApplied extends S2FBase {
933
1218
  }
934
1219
  type S2FMessage = AuthChallenge | AuthOk | PingS2F | PongS2F | ErrorMessage | EpochWeights | QuoteRequest | QuoteAck | QuoteReconfirm | TicketOffer | TicketIntentAck | TicketIssued | TicketExpired | OrderSettled | PenaltyApplied | SettleAttestations;
935
1220
  type F2SMessage = AuthResponse | PingF2S | PongF2S | ErrorF2S | QuoteMessage | QuoteReconfirmReply | TicketIntentMessage | TicketDecline | TicketReceiptMessage | FillReported;
1221
+ /** `POST /v1/filler/auth`: the bearer token of REST and of the WebSocket upgrade, bound to (fillerId, message key). */
936
1222
  interface AuthToken {
937
1223
  token: string;
938
1224
  expiresAt: TimeMs;
939
1225
  }
1226
+ /** `GET /v1/filler/auth/challenge` query. */
1227
+ interface ChallengeQuery {
1228
+ fillerId: string;
1229
+ }
940
1230
  interface Page<T> {
941
1231
  items: T[];
942
1232
  nextCursor: string | null;
@@ -1040,6 +1330,27 @@ interface SignedFillerKeyRegistration {
1040
1330
  sig: Hex;
1041
1331
  }
1042
1332
 
1333
+ /** `hashTicket` of the router: the `FillTicket` digest in the ticket domain, the same on every chain. */
1334
+ declare const hashFillTicket: (ticket: FillTicket) => Hex;
1335
+ /** The `FillerQuote` digest; `quote.requestId` is already `requestIdHash(requestId)`. */
1336
+ declare const hashFillerQuote: (quote: FillerQuote) => Hex;
1337
+ /** The `TicketIntent` digest — the inner `sig` of `ticket.intent`. */
1338
+ declare const hashTicketIntent: (intent: TicketIntent) => Hex;
1339
+ /** What `msgSig` of a filler → filler-gateway message is over: `FillerMessage{bodyHash}` of the message without `msgSig`. */
1340
+ declare const hashFillerMessage: (message: object) => Hex;
1341
+ /** The `FillerKeyRegistration` digest; the registered key signs it, and it must recover to `messageKey`. */
1342
+ declare const hashFillerKeyRegistration: (registration: FillerKeyRegistration) => Hex;
1343
+ /** `keccak256(utf8(deliveryOrderCid))` over the contract id exactly as `ticket.issued` sent it: no trimming, no case change. */
1344
+ declare function deliveryOrderCidHash(deliveryOrderCid: string): Hex;
1345
+ /**
1346
+ * The `CantonTicketReceipt` of a Canton-form ticket, from the fields that name it — the filler reads them from
1347
+ * `ticket.issued`, filler-gateway from the `ticket.receipt` it verifies; both get the same struct. Any other field of
1348
+ * the frame (`fillerId`, `repayTo`) is not part of the receipt and is ignored.
1349
+ */
1350
+ declare function cantonTicketReceipt(ticket: Pick<TicketIssuedCanton, 'orderHash' | 'attempt' | 'deliveryOrderCid' | 'validUntil'>): CantonTicketReceipt;
1351
+ /** The `CantonTicketReceipt` digest — the inner `sig` of a Canton-form `ticket.receipt`. */
1352
+ declare const hashCantonTicketReceipt: (receipt: CantonTicketReceipt) => Hex;
1353
+
1043
1354
  interface FillerEnvelopeContext {
1044
1355
  /** The `fillerId` the session (or bearer token) is authenticated for. */
1045
1356
  fillerId: string;
@@ -1098,6 +1409,61 @@ declare function drawWinner(h: bigint, candidates: readonly DrawCandidate[]): Dr
1098
1409
 
1099
1410
  /** The protocol major this package describes: the `/v1` path and `auth.response.protocolVersion`. */
1100
1411
  declare const PROTOCOL_VERSION = "1";
1412
+ /**
1413
+ * The WebSocket subprotocol of filler protocol v1. A filler offers it on the
1414
+ * upgrade of `/v1` together with `bearer.<token>`; filler-gateway answers with
1415
+ * this one only and never echoes the token.
1416
+ */
1417
+ declare const FILLER_WS_SUBPROTOCOL = "cancore-filler.v1";
1418
+ /** Prefix of the second subprotocol a filler offers: `bearer.` + the token of `POST /v1/filler/auth`. */
1419
+ declare const FILLER_WS_BEARER_PREFIX = "bearer.";
1420
+ /**
1421
+ * The subprotocols a filler offers on the upgrade (`Sec-WebSocket-Protocol`):
1422
+ * `['cancore-filler.v1', 'bearer.<token>']`. In a browser
1423
+ * `new WebSocket(url, fillerWsProtocols(token))`; with `ws` the same array.
1424
+ * The second entry carries the bearer token: never log it.
1425
+ */
1426
+ declare function fillerWsProtocols(token: string): readonly [string, string];
1427
+ /** Close codes filler-gateway closes a filler session with (protocol §3.1). */
1428
+ declare const FILLER_CLOSE_CODES: {
1429
+ /** filler-gateway is shutting down. */
1430
+ readonly GOING_AWAY: 1001;
1431
+ /** The filler missed its heartbeats. */
1432
+ readonly HEARTBEAT_MISSED: 4000;
1433
+ /** A newer session of this fillerId superseded this one. */
1434
+ readonly SUPERSEDED: 4001;
1435
+ /** Cancore staff changed the message key the session was opened with: log in again with the new key. */
1436
+ readonly KEY_CHANGED: 4002;
1437
+ /** The filler is no longer `ACTIVE` (suspended). */
1438
+ readonly NOT_ACTIVE: 4003;
1439
+ /** This session's inbound queue overflowed (count or bytes); only this session is closed. */
1440
+ readonly QUEUE_OVERFLOW: 4008;
1441
+ /**
1442
+ * Sustained excess over the rate limits: every session of the fillerId is
1443
+ * closed and its upgrades and bearer requests are refused for a cooldown;
1444
+ * the `error RATE_LIMITED` sent just before carries `retryAfterMs` = the
1445
+ * remaining cooldown.
1446
+ */
1447
+ readonly RATE_LIMITED: 4029;
1448
+ };
1449
+ type FillerCloseCode = (typeof FILLER_CLOSE_CODES)[keyof typeof FILLER_CLOSE_CODES];
1450
+ /**
1451
+ * HTTP statuses filler-gateway refuses the WebSocket upgrade with — a plain
1452
+ * HTTP response, no WebSocket, nothing signed. A client sees the upgrade fail
1453
+ * before the socket opens.
1454
+ */
1455
+ declare const FILLER_UPGRADE_REFUSALS: {
1456
+ /** `cancore-filler.v1` not offered, or not exactly one `bearer.` entry. */
1457
+ readonly 400: "BAD_REQUEST";
1458
+ /** The token is missing, unknown or expired, or the message key changed. */
1459
+ readonly 401: "UNAUTHENTICATED";
1460
+ /** The filler is unknown or not `ACTIVE`. */
1461
+ readonly 403: "NOT_ACTIVE";
1462
+ /** The login rate class is over its limit, or the fillerId is cooling down; `Retry-After` in seconds. */
1463
+ readonly 429: "RATE_LIMITED";
1464
+ /** The replica is at its connection limit, or the fillerId already holds its maximum of live sessions. */
1465
+ readonly 503: "UNAVAILABLE";
1466
+ };
1101
1467
  interface FillerGateway {
1102
1468
  /** The key every S→F message is signed with (`GatewayMessage`); null until the environment has one. */
1103
1469
  gateway: Hex | null;
@@ -1122,6 +1488,8 @@ interface RestEndpoint {
1122
1488
  request?: string;
1123
1489
  query?: string;
1124
1490
  response: string;
1491
+ /** An unsigned refusal body (`unsignedErrorBody`) this endpoint may answer instead of the signed `error` (the login routes). Every 429 is one, on every route. */
1492
+ errorBody?: string;
1125
1493
  }
1126
1494
  declare const PROTOCOL_SCHEMAS: {
1127
1495
  readonly messages: JsonSchema;
@@ -1133,6 +1501,11 @@ declare const ASYNCAPI: JsonSchema;
1133
1501
  declare const SCHEMA_VOCABULARY: readonly string[];
1134
1502
  /** Frame type → who sends it: S2F gateway to taker, F2S taker to gateway, both. */
1135
1503
  declare const MESSAGE_DIRECTIONS: Readonly<Record<string, MessageDirection>>;
1504
+ /**
1505
+ * Frame types that travel only as REST bodies — the login, `auth.challenge` and `auth.response` —
1506
+ * never on the WebSocket, which is authenticated by the bearer token offered on the upgrade.
1507
+ */
1508
+ declare const REST_ONLY_TYPES: readonly string[];
1136
1509
  declare const REST_ENDPOINTS: readonly RestEndpoint[];
1137
1510
  /**
1138
1511
  * The absolute `$ref` of a frame type's schema (or any other `$def` of messages.schema.json).
@@ -1146,7 +1519,7 @@ declare const CONTRACTS_RELEASE: {
1146
1519
  readonly version: "1.4.0-dev";
1147
1520
  readonly releaseChannel: "dev";
1148
1521
  readonly updatedAt: "2026-07-24T19:55:00Z";
1149
- readonly commit: "8c7d36f6a4f1cb76e6d5098c4f4b18367d46e350";
1522
+ readonly commit: "c214f56f6fe5a62097833c5f1335b0cb5351b225";
1150
1523
  };
1151
1524
  /**
1152
1525
  * Per contract, the build of the release, as evm-contracts
@@ -1178,10 +1551,10 @@ declare const BUILD_HASHES: {
1178
1551
  readonly runtimeHexLength: 2394;
1179
1552
  };
1180
1553
  readonly CancoreRouter: {
1181
- readonly creationHexSha256: "615b6fb47a4255df9f7fdec963811cdfbefb53166645cd19466fa268df7fb39d";
1182
- readonly runtimeHexSha256: "dec1f5d541c6b383b95b6c53e278123cc3844bdeff3f977a166fb6e9cbf86343";
1183
- readonly creationHexLength: 43102;
1184
- readonly runtimeHexLength: 36984;
1554
+ readonly creationHexSha256: "43f61c94c1bb04ee4a0f3ad39356744e6b542eb9945ce4f0561665e049d451b0";
1555
+ readonly runtimeHexSha256: "0c826474f8df21fdceefaf5234d3c50e0a8afcdf3124beb002aed4585227de72";
1556
+ readonly creationHexLength: 40820;
1557
+ readonly runtimeHexLength: 35248;
1185
1558
  };
1186
1559
  readonly CNRXStaking: {
1187
1560
  readonly creationHexSha256: "dfda056ee22b593e2f2e1fc4e679fbb9dc34b04964f389b46914402c422b40fb";
@@ -1234,10 +1607,10 @@ declare const BYTECODE_HASHES: {
1234
1607
  readonly deployedBytecodeLength: 2394;
1235
1608
  };
1236
1609
  readonly CancoreRouter: {
1237
- readonly bytecodeHash: "615b6fb47a4255df9f7fdec963811cdfbefb53166645cd19466fa268df7fb39d";
1238
- readonly deployedBytecodeHash: "dec1f5d541c6b383b95b6c53e278123cc3844bdeff3f977a166fb6e9cbf86343";
1239
- readonly bytecodeLength: 43102;
1240
- readonly deployedBytecodeLength: 36984;
1610
+ readonly bytecodeHash: "43f61c94c1bb04ee4a0f3ad39356744e6b542eb9945ce4f0561665e049d451b0";
1611
+ readonly deployedBytecodeHash: "0c826474f8df21fdceefaf5234d3c50e0a8afcdf3124beb002aed4585227de72";
1612
+ readonly bytecodeLength: 40820;
1613
+ readonly deployedBytecodeLength: 35248;
1241
1614
  };
1242
1615
  readonly CNRXStaking: {
1243
1616
  readonly bytecodeHash: "dfda056ee22b593e2f2e1fc4e679fbb9dc34b04964f389b46914402c422b40fb";
@@ -1279,4 +1652,4 @@ declare const BYTECODE_HASHES: {
1279
1652
  /** Decode a revert's 4-byte selector into the custom error it names, if it is one of ours. */
1280
1653
  declare function describeRevert(selectorOrData: string, tables: ReadonlyArray<Readonly<Record<string, string>>>): string | undefined;
1281
1654
 
1282
- export { ASYNCAPI, type AttestationCanton, type AttestationEvm, type AttestationsResponse, type AuthChallenge, type AuthOk, type AuthResponse, type AuthToken, BUILD_HASHES, BYTECODE_HASHES, CONTRACTS_RELEASE, DECLINE_REASONS, DEPLOYMENTS, DRAND_QUICKNET, DRAW_CLOSED_BY, type DecString, type DeclineReason, type DeploymentEnv, type DrawAttempt, type DrawCandidate, type DrawClosedBy, type DrawOutcome, type DrawRecord, ERROR_CODES, ERROR_HTTP_STATUS, EXEMPT_REASONS, EXPIRED_RESULTS, type EpochLeaf, type EpochRecord, type EpochWeights, type ErrorCode, type ErrorF2S, type ErrorMessage, type EvmDeployment, type ExemptReason, type ExpiredResult, type F2SBase, type F2SEnvelope, type F2SMessage, 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, type FeeClaim, type FillProof, type FillProofJson, type FillReported, type FillTicket, type FillerAuth, type FillerEnvelopeContext, type FillerGateway, type FillerKeyRegistration, type FillerMessage, type FillerQuote, type FillerStats, GATEWAY_MESSAGE_TYPES, type GatewayInfo, type GatewayMessage, type Hex, type JsonSchema, type JsonValue, MESSAGE_DIRECTIONS, type MessageDirection, ORDER_TYPES, type Order, type OrderJson, type OrderSettled, PENALTY_STEPS, PERMIT2_ADDRESS, PROOF_KIND_ATTESTATION, PROTOCOL_SCHEMAS, PROTOCOL_VERSION, type Page, type PenaltyApplied, type PenaltyList, type PenaltyRecord, type PenaltyStep, type Ping, type PingF2S, type PingS2F, type Pong, type PongF2S, type PongS2F, QUOTE_ACK_STATUSES, QUOTE_FINAL_STATUSES, QUOTE_TYPES, type Quote, type QuoteAck, type QuoteAckStatus, type QuoteFinalStatus, type QuoteList, type QuoteMessage, type QuoteReconfirm, type QuoteReconfirmReply, type QuoteRecord, type QuoteRequest, REST_ENDPOINTS, type RestEndpoint, type S2FBase, type S2FMessage, SCHEMA_VOCABULARY, STAKE_BINDING_TYPES, type SettleAttestations, type SettleAttestationsPayload, type SignedFillerKeyRegistration, type StakeBinding, type StakeBindingRequest, TICKET_INTENT_TYPES, TICKET_LIST_STATUSES, TICKET_RECEIPT_TYPES, TICKET_REFUSED_REASONS, type TicketDecline, type TicketExpired, type TicketIntent, type TicketIntentAck, type TicketIntentMessage, type TicketIssued, type TicketIssuedCanton, type TicketIssuedEvm, type TicketJson, type TicketList, type TicketOffer, type TicketReceipt, type TicketReceiptMessage, type TicketRefusedReason, type TimeMs, type TypedDataDomain, type TypedDataInput, type TypedDataTypes, type TypedField, type TypedValue, type UintLike, type WireAsset, 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 };
1655
+ export { ASYNCAPI, type AttestationCanton, type AttestationEvm, type AttestationsResponse, type AuthChallenge, type AuthOk, type AuthResponse, type AuthToken, BPS, BUILD_HASHES, BYTECODE_HASHES, CANTON_ORIGIN_ID, CANTON_SOURCE_ANCHOR, CANTON_TICKET_RECEIPT_TYPES, CONTRACTS_RELEASE, type CantonNetwork, type CantonSourceIntent, type CantonSourceOrder, type CantonTicketReceipt, type ChallengeQuery, DAML_NUMERIC_SCALE, DECLINE_REASONS, DEPLOYMENTS, DRAND_QUICKNET, DRAW_CLOSED_BY, type DecString, type DeclineReason, type DeploymentEnv, type DrawAttempt, type DrawCandidate, type DrawClosedBy, type DrawOutcome, type DrawRecord, EIP2294_MAX_CHAIN_ID, ERROR_CODES, ERROR_HTTP_STATUS, EXEMPT_REASONS, EXPIRED_RESULTS, type EpochLeaf, type EpochRecord, type EpochWeights, type ErrorCode, type ErrorF2S, type ErrorMessage, type EvmDeployment, type ExemptReason, type ExpiredResult, type F2SBase, type F2SEnvelope, type F2SMessage, 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, type FeeClaim, type FeeSplit, type FillProof, type FillProofJson, type FillReported, type FillTicket, type FillerAuth, type FillerCloseCode, type FillerEnvelopeContext, type FillerGateway, type FillerKeyRegistration, type FillerMessage, type FillerQuote, type FillerStats, GATEWAY_MESSAGE_TYPES, GRACE, type GatewayInfo, type GatewayMessage, type Hex, INSTRUMENT_LABEL_TAG, type JsonSchema, type JsonValue, MAX_FEE_BPS, MAX_FILL_TTL, MAX_PROOF_WINDOW, MAX_SIG_TTL, MESSAGE_DIRECTIONS, MIN_FILL_TTL, type MessageDirection, ORDER_TYPES, OWNER_LABEL_TAG, type Order, type OrderDomain, type OrderJson, type OrderSettled, PENALTY_STEPS, PERMIT2_ADDRESS, PERMIT2_WITNESS_TYPE_STRING, PERMIT_WITNESS_TYPES, PROOF_KIND_ATTESTATION, PROTOCOL_SCHEMAS, PROTOCOL_VERSION, type Page, type PenaltyApplied, type PenaltyList, type PenaltyRecord, type PenaltyStep, type PermitWitness, type Ping, type PingF2S, type PingS2F, type Pong, type PongF2S, type PongS2F, QUOTE_ACK_STATUSES, QUOTE_FINAL_STATUSES, QUOTE_TYPES, type Quote, type QuoteAck, type QuoteAckStatus, type QuoteFinalStatus, type QuoteList, type QuoteMessage, type QuoteReconfirm, type QuoteReconfirmReply, type QuoteRecord, type QuoteRequest, REST_ENDPOINTS, REST_ONLY_TYPES, type RestEndpoint, type S2FBase, type S2FMessage, SCHEMA_VOCABULARY, SET_DELAY, STAKE_BINDING_TYPES, type SettleAttestations, type SettleAttestationsPayload, type SignedFillerKeyRegistration, type StakeBinding, type StakeBindingRequest, TICKET_INTENT_TYPES, TICKET_LIST_STATUSES, TICKET_RECEIPT_TYPES, TICKET_REFUSED_REASONS, type TicketDecline, type TicketExpired, type TicketIntent, type TicketIntentAck, type TicketIntentMessage, type TicketIssued, type TicketIssuedCanton, type TicketIssuedEvm, type TicketJson, type TicketList, type TicketOffer, type TicketReceipt, type TicketReceiptCanton, type TicketReceiptEvm, type TicketReceiptMessage, type TicketRefusedReason, type TimeMs, type TypedDataDomain, type TypedDataInput, type TypedDataTypes, type TypedField, type TypedValue, type UintLike, type UnsignedErrorBody, type WireAsset, 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 };