@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/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
|
|
150
|
-
| `rest.schema.json` | REST
|
|
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
|
|
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
|
|
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
|