@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 CHANGED
@@ -63,6 +63,69 @@ the taker client relies on: those views and calls, the events `IntentOpened`, `F
63
63
  `Settled` and `Refunded`, and the 11-field `Order` tuple in the order of `ORDER_TYPES`, whose
64
64
  type hash is the router's `ORDER_TYPEHASH`. Router addresses are not in this package yet.
65
65
 
66
+ ### Orders, the Permit2 witness, the fee
67
+
68
+ Hashing helpers ship from the package root (sdk.md §7, decided: helpers, not data only). They
69
+ are what the backend, the filler node, the attestors and the web app use instead of their own
70
+ copies:
71
+
72
+ ```ts
73
+ import {
74
+ buildCantonSourceOrder, cantonInclusiveFeeSplit, hashOrder, hashPermitWitness, inclusiveFeeSplit,
75
+ MAX_FEE_BPS, MIN_FILL_TTL, sourceOrderHash,
76
+ } from '@cancore/contracts';
77
+
78
+ hashOrder(order, { chainId, verifyingContract: router }); // CancoreRouter.hashOrder: the orderHash
79
+ sourceOrderHash(order, sourceRouter); // what a destination keys `filled` on; a Canton origin needs no router
80
+
81
+ // the EVM-form Order of a Canton-source intent (protocol.md §3.7): refuses an inexact amount, fee or time
82
+ const { order, domain, orderHash } = buildCantonSourceOrder({
83
+ ownerPartyId, requestId, instrumentAdmin, instrumentId, amount: '1250.5',
84
+ destinationChainId: 1, wantToken, wantDecimals: 6, minReceived: '1200.25', recipient,
85
+ createdAt, fillDeadline, feeRate: '0.003', cantonOriginId: CANTON_ORIGIN_ID.devnet,
86
+ });
87
+
88
+ // what the maker signs for openFor: Permit2 PermitWitnessTransferFrom, the order as witness (PERMIT_WITNESS_TYPES for the wallet)
89
+ const digest = hashPermitWitness({ permitted: { token, amount }, spender: router, nonce, deadline, witness: order }, chainId);
90
+
91
+ inclusiveFeeSplit(105n, 500); // { payout: 100n, fee: 5n } — EVM source, CancoreRouter.settle (floor)
92
+ cantonInclusiveFeeSplit(total, 30); // Canton source, Daml inclusiveFee (half-even at 10⁻¹⁰)
93
+ ```
94
+
95
+ | Constants | Value | Held to |
96
+ | --- | --- | --- |
97
+ | `BPS`, `MAX_FEE_BPS`, `MIN_FILL_TTL`, `PROOF_KIND_ATTESTATION` | 10 000, 1 000, 60 s, 1 | `CancoreRouter.sol` via `spec/constants.json` |
98
+ | `MAX_FILL_TTL`, `MAX_SIG_TTL`, `MAX_PROOF_WINDOW`, `GRACE`, `SET_DELAY` | 24 h, 24 h, 4 h, 28 h, 72 h (seconds) | `AttestorSet.sol` via `spec/constants.json` |
99
+ | `CANTON_ORIGIN_ID`, `CANTON_SOURCE_ANCHOR`, `EIP2294_MAX_CHAIN_ID`, `OWNER_LABEL_TAG`, `INSTRUMENT_LABEL_TAG`, `DAML_NUMERIC_SCALE` | protocol.md §3.8 | `spec/vectors/canton-order.json` |
100
+
101
+ **Canton destination** (protocol.md §3.13). An EVM-source order delivered on Canton, and the
102
+ `FillProof` of the delivery, carry Canton values in EVM fields; this is the one encoder for them:
103
+
104
+ ```ts
105
+ import {
106
+ cantonNetworkOfDestination, encodeCantonAmount, encodeCantonDestination, encodeCantonOutputAsset, encodeCantonRecipient,
107
+ } from '@cancore/contracts';
108
+
109
+ const destination = encodeCantonDestination('devnet'); // keccak256(utf8("canton:devnet"))
110
+ const outputAsset = encodeCantonOutputAsset({ admin, id: 'USDCX' }); // keccak256(abi.encode("cancore:instrument:v1", admin, id))
111
+ const minReceived = encodeCantonAmount('1200.25'); // Daml Numeric 10 × 10¹⁰, exact or refused
112
+ const recipient = encodeCantonRecipient(partyId); // keccak256(utf8(partyId))
113
+ cantonNetworkOfDestination(order.destination); // 'devnet' | 'testnet' | 'mainnet' | undefined
114
+ ```
115
+
116
+ `spec/vectors/canton-destination.json` holds such an order (devnet) with its `orderHash` and the
117
+ `FillProof` of its delivery with its digest; its instrument, party and amount are those of the
118
+ Canton-destination vector of `spec/typed-data/FillProof.json` (`canton:mainnet`), which the
119
+ router test computes with `hashFillProof`.
120
+
121
+ `spec/constants.json` is written by `npm run sync` from the Solidity source of the same
122
+ evm-contracts commit as the ABIs (`CONTRACTS_RELEASE.commit`); a test holds every exported
123
+ constant to it, fails on a numeric constant the package does not export, and checks the router's
124
+ type hashes and `WITNESS_TYPE_STRING` against the package's type strings. Vectors:
125
+ `spec/vectors/evm-order.json`, `permit-witness.json` and `fee-split.json` (both rails; each EVM
126
+ case names the router test that pins it, each Canton case carries the Daml values), generated with
127
+ ethers by `scripts/gen-router-vectors.mjs`.
128
+
66
129
  ## FillProof: what attestors sign
67
130
 
68
131
  `CancoreRouter.settle(order, proof, sigs)` pays a filler out only against k attestor
@@ -98,7 +161,7 @@ breaking protocol change is `0.3`.
98
161
 
99
162
  ```ts
100
163
  import {
101
- gatewayBodyHash, hashFillerMessage, hashTicketIntent, repayToFromEvm, fillerIdHash,
164
+ cantonTicketReceipt, gatewayBodyHash, hashCantonTicketReceipt, hashFillerMessage, hashTicketIntent, repayToFromEvm, fillerIdHash,
102
165
  } from '@cancore/contracts';
103
166
 
104
167
  // what the filler's message key signs to take an offered ticket: its delivery key and payout address
@@ -116,6 +179,9 @@ const msgDigest = hashFillerMessage(message); // bodyHash = keccak256(JCS(messag
116
179
  const bodyHash = gatewayBodyHash(frame); // keccak256(JCS(frame without sig))
117
180
 
118
181
  fillerIdHash('acme'); // the on-chain fillerId of FillTicket, Filled, FillProof, Settled
182
+
183
+ // the receipt of a Canton-form ticket (no FillTicket, no ticketSig): built from ticket.issued
184
+ const receiptDigest = hashCantonTicketReceipt(cantonTicketReceipt(issued)); // orderHash, attempt, keccak256(cid), validUntil
119
185
  ```
120
186
 
121
187
  `hashTypedData` encodes flat structs (address, bool, bytes, bytesN, string, uintN) and throws on
@@ -130,6 +196,7 @@ manual key change by Cancore staff; there is no key-rotation type or message.
130
196
  | --- | --- | --- |
131
197
  | `TicketReceipt`, `StakeBinding`, `FillerAuth`, `GatewayMessage` | `CancoreFillerProtocol` v1 | v1 RC — vectors in `spec/protocol/typed-data/` |
132
198
  | `FillerQuote` (`string fillerId`), `TicketIntent` (with `fillerId`, `deliveryKey`, `repayTo`), `FillerMessage`, `FillerKeyRegistration` | `CancoreFillerProtocol` v1 | variant A — vectors in `spec/protocol/typed-data/` |
199
+ | `CantonTicketReceipt` (`orderHash`, `attempt`, `deliveryOrderCidHash`, `validUntil`) | `CancoreFillerProtocol` v1 | receipt of a Canton-form ticket (§10 D-O), additive — vectors in `spec/protocol/typed-data/` |
133
200
  | `Order` (11 fields, with `createdAt`), `Quote` | `CancoreRouter` v1, source router | router code; provisional copies in `spec/typed-data/` until evm-contracts publishes them |
134
201
  | `FillTicket` (`orderHash`, `fillerId`, `deliveryKey`, `repayTo`, `attempt`, `validFrom`, `validUntil`) | `CancoreFillTicket` v1 | variant A, synced from the router (CAN-2140) |
135
202
  | `FillProof` (twelve fields) | `CancoreRouter` v1, source router | variant A, synced from the router (above) |
@@ -146,15 +213,15 @@ drand quicknet rounds.
146
213
 
147
214
  | File (`@cancore/contracts/spec/protocol/…`) | Holds |
148
215
  | --- | --- |
149
- | `messages.schema.json` | one `$def` per WebSocket frame type (23), `x-direction` S2F / F2S / both, and the primitives they share |
150
- | `rest.schema.json` | REST fallback bodies; `x-endpoints` (method, path, auth, request/response), `x-error-status` |
216
+ | `messages.schema.json` | one `$def` per frame type (23), `x-direction` S2F / F2S / both, `x-rest-only` on the two login types, and the primitives they share |
217
+ | `rest.schema.json` | REST bodies; `x-endpoints` (method, path, auth, query, request/response, `errorBody` where a refusal may be unsigned), `x-error-status` |
151
218
  | `records.schema.json` | the draw record, the epoch record, `GET /v1/gateway` |
152
- | `asyncapi.json` | AsyncAPI 3.0: channel `/v1`, the gateway's send/receive operations, examples |
219
+ | `asyncapi.json` | AsyncAPI 3.0: channel `/v1` (the upgrade's subprotocols, its HTTP refusals `x-upgrade-refusals`, the close codes `x-close-codes`), the gateway's send/receive operations, examples |
153
220
  | `vectors/messages.json`, `vectors/records.json` | valid example frames and fixture records (hashes real, `sig` a placeholder: r = s = 0, v = 27) |
154
221
  | `vectors/settle-attestations.json` | `settle.attestations` golden vectors: EVM and Canton source, real TEST-key signatures, the pushed frame and the REST body with one payload, and schema-valid payloads a filler must refuse |
155
222
 
156
- The same objects are exported as `PROTOCOL_SCHEMAS`, `ASYNCAPI`, `MESSAGE_DIRECTIONS` and
157
- `REST_ENDPOINTS`, with TypeScript shapes of every frame (`TicketOffer`, `QuoteAck`, …) and the
223
+ The same objects are exported as `PROTOCOL_SCHEMAS`, `ASYNCAPI`, `MESSAGE_DIRECTIONS`,
224
+ `REST_ONLY_TYPES` and `REST_ENDPOINTS`, with TypeScript shapes of every frame (`TicketOffer`, `QuoteAck`, …) and the
158
225
  enums (`DECLINE_REASONS`, `ERROR_CODES`, …) a test holds to the schemas.
159
226
 
160
227
  ```ts
@@ -186,6 +253,31 @@ filler's `msgSig` (`pingF2S`); the second argument of `messageSchemaRef` picks o
186
253
  `scripts/gen-protocol-docs.mjs` derives the examples, records and the AsyncAPI document from
187
254
  the schemas and the vectors.
188
255
 
256
+ ### Login and connect
257
+
258
+ A filler logs in over REST and only then opens the WebSocket:
259
+
260
+ 1. `GET /v1/filler/auth/challenge?fillerId=<fillerId>` → a signed `auth.challenge` addressed to that
261
+ `fillerId`. Check its `sig` against the published gateway key and that `fillerId` is yours.
262
+ Refusals of this anonymous route are unsigned (`unsignedErrorBody`): 400 `BAD_REQUEST`, 404
263
+ `UNKNOWN_REQUEST` (unknown or not `ACTIVE`), 429 `RATE_LIMITED` with `retryAfterMs`.
264
+ 2. `POST /v1/filler/auth` with `auth.response` (`FillerAuth` by the message key, `nonce` = the
265
+ challenge's) → `{token, expiresAt}`, bound to `(fillerId, message key)`. Refusals decided before
266
+ any signature check are unsigned too: 400 `BAD_REQUEST`, 404 `UNKNOWN_REQUEST`, 401
267
+ `UNAUTHENTICATED` (no live challenge for the fillerId: start again from step 1), 429; refusals after
268
+ the signature checks are the signed `error`.
269
+ 3. Upgrade `/v1` offering `fillerWsProtocols(token)` = `['cancore-filler.v1', 'bearer.<token>']`
270
+ (`FILLER_WS_SUBPROTOCOL`, `FILLER_WS_BEARER_PREFIX`) as `Sec-WebSocket-Protocol`; the gateway
271
+ answers `cancore-filler.v1` and sends a signed `auth.ok` first. It refuses with plain HTTP
272
+ (`FILLER_UPGRADE_REFUSALS`: 400, 401, 403, 429 with `Retry-After`, 503) and closes a session
273
+ with one of `FILLER_CLOSE_CODES` (4029: rate-limit cooldown, preceded by `error RATE_LIMITED`
274
+ whose `retryAfterMs` is the remaining cooldown).
275
+
276
+ The same token authenticates REST (`Authorization: Bearer`). `auth.challenge` and
277
+ `auth.response` never travel on the socket (`REST_ONLY_TYPES`). Over a per-fillerId rate limit
278
+ the gateway answers `error RATE_LIMITED` with `retryAfterMs` (on REST: 429, always unsigned, with
279
+ `retryAfterMs` and `Retry-After`); send nothing of that rate class before it has passed.
280
+
189
281
  ### Attestation signatures for `settle`
190
282
 
191
283
  Once filler-gateway holds at least `threshold` verified attestor signatures over a filler's
@@ -283,7 +375,8 @@ added.
283
375
  EVM_CONTRACTS_DIR=../evm-contracts npm run sync # then review the diff and release
284
376
  ```
285
377
 
286
- `npm run sync` is two scripts: `scripts/sync.mjs` (ABIs, error tables, release identity) and
378
+ `npm run sync` is two scripts: `scripts/sync.mjs` (ABIs, error tables, release identity, the
379
+ router and AttestorSet constants in `spec/constants.json`) and
287
380
  `scripts/sync-typed-data.mjs` (`abi/typed-data/*.json`). Until evm-contracts publishes
288
381
  `abi/typed-data/` the second one fails; run the first one alone:
289
382
 
@@ -306,6 +399,55 @@ Full documentation: <https://docs.cancore.io/sdk/contracts>
306
399
 
307
400
  ## Changes
308
401
 
402
+ `0.2.0-rc.9` follows `0.2.0-rc.7`: no `0.2.0-rc.8` was published. Its four entries below ship
403
+ together; the first is breaking within the RC line for a filler and for filler-gateway, the other
404
+ three are additive.
405
+
406
+ - `0.2.0-rc.9` — connect only after login, limits per fillerId (CAN-2232). **Breaking within the
407
+ RC line** for a filler and for filler-gateway:
408
+ - The login is REST only: `GET /v1/filler/auth/challenge` takes a required `fillerId` query
409
+ (`challengeQuery`), and `auth.challenge` is addressed (envelope `s2fBase`, `fillerId`
410
+ required). The refusals of the login routes decided before a signature check, and every 429,
411
+ are unsigned (`unsignedErrorBody`; `errorBody` of the two login endpoints).
412
+ `auth.challenge` and `auth.response` carry `x-rest-only` (a new annotation keyword in
413
+ `SCHEMA_VOCABULARY`; `REST_ONLY_TYPES`) and leave the AsyncAPI channel.
414
+ - The WebSocket upgrade offers `cancore-filler.v1` and `bearer.<token>`:
415
+ `FILLER_WS_SUBPROTOCOL`, `FILLER_WS_BEARER_PREFIX`, `fillerWsProtocols`; its refusals
416
+ `FILLER_UPGRADE_REFUSALS` and the session close codes `FILLER_CLOSE_CODES`, also in
417
+ `asyncapi.json` (`bindings.ws`, `x-upgrade-refusals`, `x-close-codes`).
418
+ - `error` gains optional `retryAfterMs` (an integer ≥ 1, with `RATE_LIMITED`);
419
+ `ErrorMessage.retryAfterMs`, `UnsignedErrorBody`, `ChallengeQuery`, `RestEndpoint.errorBody`.
420
+ - The `auth.challenge` example and its `GatewayMessage` vector carry `fillerId` (that vector's
421
+ digest changes); a `RATE_LIMITED` example; no other digest changes.
422
+ - `0.2.0-rc.9` — router constants and order hashing helpers (CAN-1934). Additive only:
423
+ no existing export, type or digest changes.
424
+ - Constants `BPS`, `MAX_FEE_BPS`, `MIN_FILL_TTL`, `MAX_FILL_TTL`, `MAX_SIG_TTL`,
425
+ `MAX_PROOF_WINDOW`, `GRACE`, `SET_DELAY`, `CANTON_ORIGIN_ID`, `CANTON_SOURCE_ANCHOR`,
426
+ `EIP2294_MAX_CHAIN_ID`, `OWNER_LABEL_TAG`, `INSTRUMENT_LABEL_TAG`, `DAML_NUMERIC_SCALE`;
427
+ `spec/constants.json`, synced from the Solidity source, pins them (SDK-6).
428
+ - Helpers `hashOrder`, `sourceOrderHash`, `isCantonOriginId`, `buildCantonSourceOrder` (port of
429
+ evm-contracts `test/helpers/cantonOrder.ts`, EVM destinations), `PERMIT_WITNESS_TYPES`,
430
+ `PERMIT2_WITNESS_TYPE_STRING`, `permit2Domain`, `hashPermitWitness`, `inclusiveFeeSplit` (EVM
431
+ source) and `cantonInclusiveFeeSplit` (Canton source).
432
+ - Vectors `spec/vectors/evm-order.json`, `permit-witness.json`, `fee-split.json`.
433
+ - `0.2.0-rc.9` — the Canton-destination encoder (protocol.md §3.13; CAN-1935). Additive only.
434
+ - `encodeCantonDestination(network)`, `cantonNetworkOfDestination(destination)`,
435
+ `encodeCantonOutputAsset({admin, id})`, `encodeCantonRecipient(partyId)`,
436
+ `encodeCantonAmount(amount)`, type `CantonNetwork`.
437
+ - Vector `spec/vectors/canton-destination.json`: an EVM-source order to Canton devnet and the
438
+ `FillProof` of its delivery.
439
+ - `0.2.0-rc.9` — `CantonTicketReceipt`, the receipt of a Canton-form ticket (protocol.md
440
+ §3.3, §3.5, §10 D-O; CAN-2062). Additive only (V-2): no existing type, digest or vector changes.
441
+ - Type `CantonTicketReceipt(bytes32 orderHash,uint32 attempt,bytes32 deliveryOrderCidHash,uint64 validUntil)`
442
+ in the `CancoreFillerProtocol` domain, signed by the message key; `fillerId` and `repayTo` are
443
+ not part of it (they travel in `ticket.issued`). Golden vectors in
444
+ `spec/protocol/typed-data/CantonTicketReceipt.json`.
445
+ - Helpers `CANTON_TICKET_RECEIPT_TYPES`, `hashCantonTicketReceipt`, `cantonTicketReceipt` (the
446
+ struct from a Canton-form `ticket.issued` or `ticket.receipt`) and `deliveryOrderCidHash`.
447
+ - `ticket.receipt` gains the Canton form: `form: "canton"`, `deliveryOrderCid`, `validUntil`,
448
+ `sig`; the EVM form (`form` absent or `"evm"`) is unchanged. The same body is the REST
449
+ `POST /v1/filler/tickets/{orderHash}/{attempt}/receipt`; AsyncAPI carries both examples.
450
+ `TicketReceiptMessage` is now the union `TicketReceiptEvm | TicketReceiptCanton`.
309
451
  - `0.2.0-rc.7` — sync the variant A `CancoreRouter` and `ICancoreRouter` ABIs from
310
452
  evm-contracts commit `c214f56f6fe5a62097833c5f1335b0cb5351b225` (CAN-2140).
311
453
  - Both the package root and `/abi`, and the shipped `spec/abi/` JSON, expose