@cancore/contracts 0.1.0 → 0.2.0-rc.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. package/README.md +266 -10
  2. package/dist/abi.d.ts +6086 -1675
  3. package/dist/abi.js +1 -1
  4. package/dist/{chunk-CIBYXHSX.js → chunk-IAPV7XWJ.js} +2 -2
  5. package/dist/chunk-IAPV7XWJ.js.map +1 -0
  6. package/dist/chunk-NV5IUURP.js +9252 -0
  7. package/dist/chunk-NV5IUURP.js.map +1 -0
  8. package/dist/index.d.ts +1180 -29
  9. package/dist/index.js +2600 -17
  10. package/dist/index.js.map +1 -1
  11. package/dist/networks.d.ts +2 -2
  12. package/dist/networks.js +1 -1
  13. package/package.json +10 -8
  14. package/spec/abi/AttestorSet.json +476 -0
  15. package/spec/abi/CNRX.json +1294 -0
  16. package/spec/abi/CNRXStaking.json +510 -0
  17. package/spec/abi/CancoreRouter.json +2564 -0
  18. package/spec/abi/FeeVault.json +604 -0
  19. package/spec/abi/HTLC.json +717 -0
  20. package/spec/abi/IBurnMintERC20.json +252 -0
  21. package/spec/abi/ICancoreRouter.json +1226 -0
  22. package/spec/abi/IHTLC.json +382 -0
  23. package/spec/abi/IPermit2.json +150 -0
  24. package/spec/abi/MultiBalanceChecker.json +34 -0
  25. package/spec/abi/PointsClaim.json +791 -0
  26. package/spec/protocol/asyncapi.json +1288 -0
  27. package/spec/protocol/messages.schema.json +525 -0
  28. package/spec/protocol/records.schema.json +94 -0
  29. package/spec/protocol/rest.schema.json +118 -0
  30. package/spec/protocol/typed-data/FillerAuth.json +58 -0
  31. package/spec/protocol/typed-data/FillerKeyRegistration.json +69 -0
  32. package/spec/protocol/typed-data/FillerMessage.json +115 -0
  33. package/spec/protocol/typed-data/FillerQuote.json +75 -0
  34. package/spec/protocol/typed-data/GatewayMessage.json +93 -0
  35. package/spec/protocol/typed-data/StakeBinding.json +75 -0
  36. package/spec/protocol/typed-data/TicketIntent.json +113 -0
  37. package/spec/protocol/typed-data/TicketReceipt.json +51 -0
  38. package/spec/protocol/vectors/draw.json +61 -0
  39. package/spec/protocol/vectors/jcs.json +59 -0
  40. package/spec/protocol/vectors/messages.json +523 -0
  41. package/spec/protocol/vectors/records.json +81 -0
  42. package/spec/protocol/vectors/settle-attestations.json +542 -0
  43. package/spec/typed-data/FillProof.json +227 -0
  44. package/spec/typed-data/FillTicket.json +115 -0
  45. package/spec/typed-data/Order.json +141 -0
  46. package/spec/typed-data/Quote.json +69 -0
  47. package/spec/vectors/canton-order.json +67 -0
  48. package/dist/chunk-CIBYXHSX.js.map +0 -1
  49. package/dist/chunk-ZSX67S72.js +0 -3423
  50. package/dist/chunk-ZSX67S72.js.map +0 -1
package/README.md CHANGED
@@ -1,23 +1,25 @@
1
1
  # `@cancore/contracts`
2
2
 
3
- The Cancore EVM contracts as data: the ABIs of the deployed HTLC, FeeVault and CNRX
4
- contracts, their custom-error selectors, where each is deployed per environment, the EIP-712
3
+ The Cancore EVM contracts as data: the ABIs of the HTLC, FeeVault and CNRX contracts and of
4
+ the intent rail's `CancoreRouter` and `AttestorSet`, their custom-error selectors, where each is deployed per environment, the EIP-712
5
5
  voucher `FeeVault` redeems, and the network registry the API's chain ids refer to.
6
6
 
7
7
  ```bash
8
8
  npm install @cancore/contracts
9
9
  ```
10
10
 
11
- No runtime code beyond three lookups, no dependencies. Everything is `as const`, so viem and
12
- wagmi infer function, event and error types from the ABIs.
11
+ Everything is `as const`, so viem and wagmi infer function, event and error types from the
12
+ ABIs. The only runtime code is a few lookups and the filler protocol's hashing helpers, which
13
+ need one dependency, `@noble/hashes`.
13
14
 
14
15
  ## What is here, and where it comes from
15
16
 
16
17
  | Entry | Holds | Source of truth |
17
18
  | --- | --- | --- |
18
- | `@cancore/contracts/abi` | `HTLC_ABI`, `FEE_VAULT_ABI`, `CNRX_ABI`, `IHTLC_ABI`, `IBURN_MINT_ERC20_ABI`, `IPERMIT2_ABI`, `MULTI_BALANCE_CHECKER_ABI`; `HTLC_ERRORS`, `FEE_VAULT_ERRORS`, `CNRX_ERRORS` | `Cancore-io/evm-contracts/abi/*.json` — the reviewed snapshots that repository keeps in lock-step with its compiled contracts |
19
+ | `@cancore/contracts/abi` | `HTLC_ABI`, `FEE_VAULT_ABI`, `CNRX_ABI`, `IHTLC_ABI`, `IBURN_MINT_ERC20_ABI`, `IPERMIT2_ABI`, `MULTI_BALANCE_CHECKER_ABI`, `CANCORE_ROUTER_ABI`, `ICANCORE_ROUTER_ABI`, `ATTESTOR_SET_ABI`, `CNRX_STAKING_ABI`, `POINTS_CLAIM_ABI`; an `*_ERRORS` table for each contract that declares custom errors | `Cancore-io/evm-contracts/abi/*.json` — the reviewed snapshots that repository keeps in lock-step with its compiled contracts; `CNRX` and `IBurnMintERC20` from `evm-contracts/vendor/*.json`, a build of `cancore-token-evm` vendored there |
19
20
  | `@cancore/contracts/networks` | `NETWORKS`, `networkOf`, `networkKindOf`, `networkByChainId` | the chain ids the Cancore API uses |
20
- | `@cancore/contracts` | all of the above, plus `DEPLOYMENTS` / `deploymentOf`, `FEE_CLAIM_TYPES` / `feeClaimDomain`, `BYTECODE_HASHES`, `CONTRACTS_RELEASE`, `describeRevert` | the contracts repository's `version.json` and bytecode hashes; the FeeVault contract's own struct and domain |
21
+ | `@cancore/contracts` (filler protocol v1) | EIP-712 types and domains of the intent rail, `hashTypedData` / `jcs` / `gatewayBodyHash` / `fillerMessageBodyHash` / `requestIdHash`, one digest helper per settlement type (`hashFillTicket`, `hashFillerQuote`, `hashTicketIntent`, `hashFillerMessage`, `hashFillerKeyRegistration`), `fillerIdHash` / `repayToFromEvm` / `repayToFromParty` / `isEvmRepayTo` / `evmAddressFromRepayTo`, `isEoaSignature`, `fillerEnvelopeError`, `drawValue` / `drawWinner` / `firstRoundAtOrAfter`, wire message types and enums, `FILLER_GATEWAYS` | `docs/intents/protocol.md` and `auction-and-draw.md` in Cancore-io/meta; `CancoreRouter.sol` for the code types |
22
+ | `@cancore/contracts` | all of the above, plus `DEPLOYMENTS` / `deploymentOf`, `FEE_CLAIM_TYPES` / `feeClaimDomain`, `FILL_PROOF_TYPES` / `fillProofDomain` / `hashFillProof` / `FillProof`, `BUILD_HASHES` (and its deprecated alias `BYTECODE_HASHES`), `CONTRACTS_RELEASE`, `describeRevert` | the contracts repository's `version.json` and bytecode hashes; the FeeVault contract's own struct and domain; `evm-contracts/abi/typed-data/FillProof.json` for the router's `FillProof` |
21
23
 
22
24
  The ABIs and selector tables are **generated**, never edited: `npm run sync` reads a checkout
23
25
  of `evm-contracts` (`EVM_CONTRACTS_DIR`) and rewrites `spec/abi/*.json` and
@@ -39,6 +41,180 @@ from the deployed contract — its `Claimed` event carried seven parameters wher
39
41
  emits eight — and nothing noticed, because a copied ABI decodes what it describes and
40
42
  silently misses what it does not. This package is what the app installs now.
41
43
 
44
+ ## CancoreRouter and AttestorSet
45
+
46
+ The intent rail's router, its interface and the k-of-n attestor set it inherits. A taker reads
47
+ intents, fills and filler windows off the router and follows its events:
48
+
49
+ ```ts
50
+ import { CANCORE_ROUTER_ABI, CANCORE_ROUTER_ERRORS, describeRevert } from '@cancore/contracts';
51
+
52
+ const [status, refundAfter, openedAt] = await client.readContract({
53
+ address: router, abi: CANCORE_ROUTER_ABI, functionName: 'intents', args: [orderHash],
54
+ });
55
+ const fills = await client.getContractEvents({ address: router, abi: CANCORE_ROUTER_ABI, eventName: 'Filled' });
56
+ describeRevert(revertData, [CANCORE_ROUTER_ERRORS]); // 'AlreadyFilled()' | …
57
+ ```
58
+
59
+ `ICANCORE_ROUTER_ABI` is the narrower interface (`fill`, `settle`, `refund`, `openFor`, the hash
60
+ helpers, the events); `ATTESTOR_SET_ABI` is the set on its own (`getAttestorSet`,
61
+ `currentSetId`, `isMember`, `revokedAttestors`), which `CancoreRouter` inherits. A test pins what
62
+ the taker client relies on: those views and calls, the events `IntentOpened`, `Filled`,
63
+ `Settled` and `Refunded`, and the 11-field `Order` tuple in the order of `ORDER_TYPES`, whose
64
+ type hash is the router's `ORDER_TYPEHASH`. Router addresses are not in this package yet.
65
+
66
+ ## FillProof: what attestors sign
67
+
68
+ `CancoreRouter.settle(order, proof, sigs)` pays a filler out only against k attestor
69
+ signatures over one EIP-712 `FillProof`, in the domain of the order's **source** router, and
70
+ pays `proof.repayTo`. Twelve fields: `fillerId` (`keccak256(utf8(fillerId))`) and `repayTo`
71
+ (encoded for the source chain) come from the delivery — `Filled` on an EVM destination, the
72
+ `DeliveryReceipt` on a Canton one — and sit before `attempt` and `setId`.
73
+
74
+ ```ts
75
+ import { FILL_PROOF_TYPES, fillProofDomain, hashFillProof, PROOF_KIND_ATTESTATION } from '@cancore/contracts';
76
+
77
+ const signature = await wallet.signTypedData({
78
+ domain: fillProofDomain(sourceChainId, sourceRouter),
79
+ types: FILL_PROOF_TYPES,
80
+ primaryType: 'FillProof',
81
+ message: proof, // setId: attestationSetFor(orderHash), never currentSetId
82
+ });
83
+ ```
84
+
85
+ This repository keeps golden vectors for the schema in `spec/typed-data/FillProof.json` (shipped
86
+ in the package since 0.2.0, under `@cancore/contracts/spec/*`), each with its `domainSeparator`,
87
+ `structHash` and digest, and the file's `typeHash`. The twelve-field file is written here ahead
88
+ of the router (`scripts/gen-protocol-vectors.mjs`): evm-contracts takes it byte for byte into
89
+ `abi/typed-data/FillProof.json` and checks every vector against the router's own `hashFillProof`
90
+ (CAN-2140); canton-contracts takes the Canton-source vector into its `FillProofVerify` vectors.
91
+ From then on the schema is synced from evm-contracts like the ABIs. Until then, do not run
92
+ `scripts/sync-typed-data.mjs` against an evm-contracts checkout that still has the eleven-field
93
+ struct: it would overwrite this file with the old one.
94
+
95
+ ## Filler protocol v1 (RC)
96
+
97
+ The wire protocol between a taker and the Cancore filler gateway, frozen as a release
98
+ candidate in `0.2.0-rc.1` (npm dist-tag `next`). In `0.x` protocol v1 is the `0.2.x` line; a
99
+ breaking protocol change is `0.3`.
100
+
101
+ ```ts
102
+ import {
103
+ gatewayBodyHash, hashFillerMessage, hashTicketIntent, repayToFromEvm, fillerIdHash,
104
+ } from '@cancore/contracts';
105
+
106
+ // what the filler's message key signs to take an offered ticket: its delivery key and payout address
107
+ const intentDigest = hashTicketIntent({
108
+ orderHash, attempt, validFrom, validUntil,
109
+ fillerId: 'acme',
110
+ deliveryKey, // the address that will send fill (zero for a Canton destination)
111
+ repayTo: repayToFromEvm(payout), // EVM source; repayToFromParty(partyId) for a Canton source
112
+ });
113
+
114
+ // what msgSig of EVERY filler → filler-gateway message is over: FillerMessage{bodyHash}
115
+ const msgDigest = hashFillerMessage(message); // bodyHash = keccak256(JCS(message without msgSig))
116
+
117
+ // what every S→F frame's `sig` is over: GatewayMessage{bodyHash} in the same domain
118
+ const bodyHash = gatewayBodyHash(frame); // keccak256(JCS(frame without sig))
119
+
120
+ fillerIdHash('acme'); // the on-chain fillerId of FillTicket, Filled, FillProof, Settled
121
+ ```
122
+
123
+ `hashTypedData` encodes flat structs (address, bool, bytes, bytesN, string, uintN) and throws on
124
+ anything else; it takes wire values as they come — decimal strings, numbers or bigints. There
125
+ is no signing in this package: hand the digest to your own secp256k1 key. The filler signs
126
+ everything with one message key, an EOA: 65 bytes `r ‖ s ‖ v`, low-s, `v ∈ {27, 28}`, no
127
+ EIP-1271 — `isEoaSignature` checks that shape before recovery. A message key is registered
128
+ with `FillerKeyRegistration` signed by that key, at onboarding and, with the new key, at a
129
+ manual key change by Cancore staff; there is no key-rotation type or message.
130
+
131
+ | Types | Domain | Status |
132
+ | --- | --- | --- |
133
+ | `TicketReceipt`, `StakeBinding`, `FillerAuth`, `GatewayMessage` | `CancoreFillerProtocol` v1 | v1 RC — vectors in `spec/protocol/typed-data/` |
134
+ | `FillerQuote` (`string fillerId`), `TicketIntent` (with `fillerId`, `deliveryKey`, `repayTo`), `FillerMessage`, `FillerKeyRegistration` | `CancoreFillerProtocol` v1 | settlement design (variant A), next RC — vectors in `spec/protocol/typed-data/` |
135
+ | `Order` (11 fields, with `createdAt`), `Quote` | `CancoreRouter` v1, source router | router code; provisional copies in `spec/typed-data/` until evm-contracts publishes them |
136
+ | `FillTicket` (`orderHash`, `fillerId`, `deliveryKey`, `repayTo`, `attempt`, `validFrom`, `validUntil`) | `CancoreFillTicket` v1 | variant A, written here ahead of the router (CAN-2140) |
137
+ | `FillProof` (twelve fields) | `CancoreRouter` v1, source router | variant A, written here ahead of the router (above) |
138
+
139
+ Golden vectors are generated with ethers by `scripts/gen-protocol-vectors.mjs` from the literal
140
+ inputs in `scripts/protocol-fixtures.mjs`, and checked by this package's own encoder too. The
141
+ `canton` Order vector equals `spec/vectors/canton-order.json`, a byte copy of
142
+ `evm-contracts/test/vectors/canton-order.json` at `f936594`, which the router's test pins.
143
+ `spec/protocol/vectors/jcs.json` holds RFC 8785 cases and `draw.json` the draw of
144
+ auction-and-draw §3.7 (r = 417828, acme-markets) plus the test-kit fixture draw, both on real
145
+ drand quicknet rounds.
146
+
147
+ ### Schemas, AsyncAPI, examples
148
+
149
+ | File (`@cancore/contracts/spec/protocol/…`) | Holds |
150
+ | --- | --- |
151
+ | `messages.schema.json` | one `$def` per WebSocket frame type (23), `x-direction` S2F / F2S / both, and the primitives they share |
152
+ | `rest.schema.json` | REST fallback bodies; `x-endpoints` (method, path, auth, request/response), `x-error-status` |
153
+ | `records.schema.json` | the draw record, the epoch record, `GET /v1/gateway` |
154
+ | `asyncapi.json` | AsyncAPI 3.0: channel `/v1`, the gateway's send/receive operations, examples |
155
+ | `vectors/messages.json`, `vectors/records.json` | valid example frames and fixture records (hashes real, `sig` a placeholder: r = s = 0, v = 27) |
156
+ | `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 |
157
+
158
+ The same objects are exported as `PROTOCOL_SCHEMAS`, `ASYNCAPI`, `MESSAGE_DIRECTIONS` and
159
+ `REST_ENDPOINTS`, with TypeScript shapes of every frame (`TicketOffer`, `QuoteAck`, …) and the
160
+ enums (`DECLINE_REASONS`, `ERROR_CODES`, …) a test holds to the schemas.
161
+
162
+ ```ts
163
+ import Ajv2020 from 'ajv/dist/2020';
164
+ import { PROTOCOL_SCHEMAS, SCHEMA_VOCABULARY, messageSchemaRef } from '@cancore/contracts';
165
+
166
+ const ajv = new Ajv2020({ strict: true });
167
+ ajv.addVocabulary([...SCHEMA_VOCABULARY]);
168
+ for (const schema of Object.values(PROTOCOL_SCHEMAS)) ajv.addSchema(schema);
169
+ ajv.validate(messageSchemaRef(frame.type, 'S2F'), frame); // errors name the field: instancePath "/amountOut"
170
+ ```
171
+
172
+ The schemas describe what a v1 **sender** emits: lowercase hex, uint64 and wider as decimal
173
+ strings, times in milliseconds, every frame with `id`, `fillerId` and `sentAt`, every S→F frame
174
+ signed with `sig` and every F→S frame — `ticket.decline`, a declining `quote.reconfirm.reply`,
175
+ `fill.reported`, `pong` and `error` included — with `msgSig` (`f2sEnvelope`); REST request
176
+ bodies carry the same envelope. `fillerEnvelopeError` runs the key-free checks of §3.4 (shape of
177
+ `msgSig`, the session's `fillerId`, freshness, `id`); recovering `msgSig` against the registered
178
+ message key and refusing a replayed `id` stay with the receiver, which keeps an accepted `id` until
179
+ `messageIdRetainUntil(sentAt, receivedAt, maxMessageAgeMs)` — freshness is symmetric, so a sender
180
+ clock running ahead keeps a message fresh past `receivedAt + maxMessageAgeMs`. The `repayToEvm` definition
181
+ refuses a `repayTo` with non-zero top 12 bytes, for a receiver that knows the source is EVM. No
182
+ object is closed: a receiver ignores unknown fields and a taker ignores unknown S→F types
183
+ (V-2), so check a frame of an unknown type against `s2fEnvelope` and skip it. Every enum is
184
+ open the same way: the known values, or any UPPER_SNAKE value added within v1, which a receiver
185
+ treats as `OTHER`/generic; a `ticket.issued` of an unknown `form` is checked on its common fields
186
+ only. `ping`, `pong` and `error` go both ways: the gateway's copy carries `sig` (`pingS2F`), the
187
+ filler's `msgSig` (`pingF2S`); the second argument of `messageSchemaRef` picks one.
188
+ `scripts/gen-protocol-docs.mjs` derives the examples, records and the AsyncAPI document from
189
+ the schemas and the vectors.
190
+
191
+ ### Attestation signatures for `settle`
192
+
193
+ Once filler-gateway holds at least `threshold` verified attestor signatures over a filler's
194
+ `FillProof`, it pushes `settle.attestations` to that filler and serves the same payload on
195
+ `GET /v1/filler/attestations/{orderHash}` (404 `ATTESTATIONS_NOT_READY` before that, 404
196
+ `UNKNOWN_TICKET` when the filler holds no ticket on the order); the filler node submits `settle`
197
+ itself (protocol §3.5, §3.6, §10 D-N). `proof` is the `FillProof` the source router hashes,
198
+ field for field (`FILL_PROOF_TYPES`); variant A of protocol §3.3 (`fillerId`, `repayTo`) replaces
199
+ it together with the router's struct. A signature entry follows `sourceChainId`: `{signer, signature}` with a
200
+ 65-byte signature on an EVM source, `{signer, pubKey, signature}` with the DER public key and a
201
+ minimal DER signature on a Canton source, as `SwapIntent_SettleWithProof` takes them.
202
+
203
+ ```ts
204
+ import { settleAttestationsErrors, settleAttestationsPayload, settleAttestationsPayloadHash, settleSigs } from '@cancore/contracts';
205
+
206
+ const payload = settleAttestationsPayload(frame); // the same from WebSocket and REST
207
+ settleAttestationsErrors(payload); // [] or what the schema cannot state: threshold, signer order, ids
208
+ settleAttestationsPayloadHash(frame); // dedupe the two channels
209
+ settleSigs(payload); // EVM: the sigs of settle(order, proof, sigs); Canton: cantonSigEntries(payload)
210
+ ```
211
+
212
+ Recover every signer and check it against `attestationSetFor(orderHash)` with your own
213
+ secp256k1 library (T-7). `scripts/gen-settle-attestations.mjs` writes the vectors.
214
+
215
+ `FILLER_GATEWAYS` is where the gateway key and the ticket signers of each environment are
216
+ published. It is empty in the RC: no gateway key exists yet.
217
+
42
218
  ## Reverts
43
219
 
44
220
  ```ts
@@ -54,7 +230,7 @@ decode against the same table.
54
230
  ## Deployments
55
231
 
56
232
  ```ts
57
- import { DEPLOYMENTS, deploymentOf, BYTECODE_HASHES } from '@cancore/contracts';
233
+ import { DEPLOYMENTS, deploymentOf, BUILD_HASHES } from '@cancore/contracts';
58
234
 
59
235
  const { htlc, htlcBlock } = deploymentOf('mainnet', 'arbitrum')!;
60
236
  ```
@@ -62,9 +238,16 @@ const { htlc, htlcBlock } = deploymentOf('mainnet', 'arbitrum')!;
62
238
  Three environments, three independent deployments: what is on Sepolia for the dev stand is
63
239
  not what is on Sepolia for testnet. `htlcBlock` is the floor for an event scan.
64
240
 
65
- An address is a claim; `BYTECODE_HASHES` is the proof. The runtime code at any `htlc`
66
- address hashes to `BYTECODE_HASHES.HTLC.deployedBytecodeHash` for the release it was deployed
67
- from, and `CONTRACTS_RELEASE` names that release.
241
+ `BUILD_HASHES` pins the build each release was made from, as `evm-contracts` records it in
242
+ `scripts/tools/check-bytecode-match.mjs`: `creationHexSha256` and `runtimeHexSha256` are sha256
243
+ of the UTF-8 text of the artifact's `0x`-prefixed hex (creation and runtime code) — not
244
+ keccak256, and not of the bytes — and `creationHexLength` / `runtimeHexLength` are the length
245
+ of that text, `0x` included. `BYTECODE_HASHES` is the same data under the old field names
246
+ (`bytecodeHash`, `deployedBytecodeHash`, `bytecodeLength`, `deployedBytecodeLength`); it is
247
+ deprecated and goes before `0.2.0`. It is not a hash of `eth_getCode`: a contract with
248
+ immutables (`CancoreRouter`, `FeeVault`) never matches one, so checking a live deployment
249
+ against it means rebuilding the release, not hashing the address. `CONTRACTS_RELEASE` names the
250
+ release.
68
251
 
69
252
  ## The FeeClaim voucher
70
253
 
@@ -102,11 +285,84 @@ added.
102
285
  EVM_CONTRACTS_DIR=../evm-contracts npm run sync # then review the diff and release
103
286
  ```
104
287
 
288
+ `npm run sync` is two scripts: `scripts/sync.mjs` (ABIs, error tables, release identity) and
289
+ `scripts/sync-typed-data.mjs` (`abi/typed-data/*.json`). Until evm-contracts publishes
290
+ `abi/typed-data/` the second one fails; run the first one alone:
291
+
292
+ ```bash
293
+ EVM_CONTRACTS_DIR=../evm-contracts node scripts/sync.mjs
294
+ ```
295
+
296
+ `EVM_CONTRACTS_DIR` must be the root of a clean git checkout of `evm-contracts`: the sync records
297
+ its `HEAD` as `CONTRACTS_RELEASE.commit` and refuses a directory that is not a checkout root or
298
+ has uncommitted changes, so the release cannot name a commit its data did not come from.
299
+
300
+ It reads `abi/*.json` except the two manifests (`bytecode-hashes.json`, `versions.json`) and
301
+ `vendor/*.json` (the `.abi` field), and refuses to run when `spec/abi/` holds a snapshot the
302
+ source no longer has — dropping a published ABI is a decision, not a side effect of a sync.
303
+
105
304
  A contract change is a release of this package. `CONTRACTS_RELEASE.version` says which
106
305
  `evm-contracts` version the data was taken from.
107
306
 
108
307
  Full documentation: <https://docs.cancore.io/sdk/contracts>
109
308
 
309
+ ## Changes
310
+
311
+ - Unreleased (next RC) — the settlement design of variant A (protocol.md §3.3, §3.4, §3.15,
312
+ §3.16; CAN-2139). **Breaking within the RC line**: every digest of the changed types changes.
313
+ - `FillTicket` is `(orderHash, bytes32 fillerId, address deliveryKey, bytes32 repayTo, attempt,
314
+ validFrom, validUntil)`; `FillProof` has twelve fields, `fillerId` and `repayTo` in place of
315
+ `address filler`; `TicketIntent` adds `string fillerId`, `deliveryKey`, `repayTo`;
316
+ `FillerQuote` names `string fillerId` instead of `address filler`. Type hashes:
317
+ `FillTicket` `0x3b13cc38…73ec82`, `FillProof` `0xc37e18cd…2419ae`.
318
+ - New types `FillerMessage(bytes32 bodyHash)` (the envelope signature `msgSig` of every filler
319
+ message) and `FillerKeyRegistration(string fillerId,address messageKey,uint64 issuedAt)`
320
+ (proof of possession of the message key, also for a manual key change by staff). No
321
+ key-rotation type, no `key.rotate` message, no refund-redirect type.
322
+ - Helpers: `hashFillTicket`, `hashFillProof`, `hashFillerQuote`, `hashTicketIntent`,
323
+ `hashFillerMessage`, `hashFillerKeyRegistration`, `fillerMessageBodyHash`, `fillerIdHash`,
324
+ `repayToFromEvm`, `repayToFromParty`, `isEvmRepayTo`, `evmAddressFromRepayTo`,
325
+ `isEoaSignature`, `fillerEnvelopeError`, `messageIdRetainUntil`.
326
+ - Schemas: every F→S frame carries `id`, `fillerId`, `sentAt`, `msgSig` (`f2sEnvelope`), as does
327
+ the stake-binding REST body; every S→F frame carries `id`; `error` goes both ways
328
+ (`errorS2F`, `errorF2S`); `quote` drops `filler`; `ticket.intent` adds `deliveryKey`,
329
+ `repayTo`; the issued EVM ticket is the seven-field `FillTicket` and the Canton form adds
330
+ `repayTo`; error codes `STALE_MESSAGE`, `REPLAYED_MESSAGE`, `TICKET_REFUSED` with
331
+ `reason` (`TICKET_REFUSED_REASONS`); `repayToEvm`, `fillerKeyRegistration` definitions;
332
+ `sig65` refuses an `s` with its top bit set; `GET /v1/gateway` returns `maxMessageAgeMs`.
333
+ - Vectors for every new and changed type; `FillProof.json` is written here ahead of the
334
+ router (see «FillProof: what attestors sign»).
335
+ - Unreleased (CAN-2018) — filler-gateway → filler `settle.attestations` and `GET /v1/filler/attestations/{orderHash}`
336
+ (protocol §3.5, §3.6, §10 D-N): the frame schema with the router's `FillProof` and the EVM and
337
+ Canton signature entries, the REST endpoint, the error code `ATTESTATIONS_NOT_READY` (404), an
338
+ AsyncAPI message, golden vectors (`spec/protocol/vectors/settle-attestations.json`), the
339
+ `SettleAttestations` types and the helpers `settleAttestationsPayload`,
340
+ `settleAttestationsPayloadHash`, `settleAttestationsErrors`, `settleSigs`, `cantonSigEntries`.
341
+ Additive only (V-2): no existing frame, type or vector changes.
342
+ - `0.2.0-rc.6` — `auth.response` gains an optional `nonce` (bytes32): the `auth.challenge` nonce it
343
+ answers, so filler-gateway's REST login (`POST /v1/filler/auth`) finds the challenge without trying
344
+ every live one. Additive only (V-2); the `FillerAuth` type and every digest are unchanged.
345
+ - `0.2.0-rc.5` — `CONTRACTS_RELEASE.commit`: the evm-contracts commit the data was synced from.
346
+ The sync takes it from the checkout's `HEAD` and refuses a directory that is not a clean
347
+ checkout root. Additive only.
348
+ - `0.2.0-rc.4` — adds `BUILD_HASHES`: the release's build hashes under names that say what they
349
+ are (`creationHexSha256`, `runtimeHexSha256`, `creationHexLength`, `runtimeHexLength`).
350
+ `BYTECODE_HASHES` keeps the same values under the old names, deprecated, and is removed before
351
+ `0.2.0`. Additive only.
352
+ - `0.2.0-rc.3` — adds the `CNRXStaking` and `PointsClaim` ABIs with their error tables
353
+ (`CNRX_STAKING_ABI`, `CNRX_STAKING_ERRORS`, `POINTS_CLAIM_ABI`, `POINTS_CLAIM_ERRORS`). The
354
+ generator now splits an acronym of two or more capitals from the word after it, which renames
355
+ nothing already exported. Additive only. Neither contract has an address in `DEPLOYMENTS`
356
+ yet; addresses come in a later release.
357
+ - `0.2.0-rc.2` — adds the `CancoreRouter`, `ICancoreRouter` and `AttestorSet` ABIs with their error
358
+ tables; `FeeVault` gains the `TransferFailed()` error and `IPermit2` gains
359
+ `permitWitnessTransferFrom`; CNRX and IBurnMintERC20 are now read from `evm-contracts/vendor/`.
360
+ Additive only. Documentation correction: `BYTECODE_HASHES` values have always been sha256 of
361
+ the artifact's hex text, never keccak256 or a hash of `eth_getCode`, as the `0.1.x` README
362
+ said; the values' meaning is unchanged.
363
+ - `0.2.0-rc.1` — filler protocol v1 release candidate: EIP-712 types, hashing helpers, JSON
364
+ Schemas, AsyncAPI, golden vectors; the `FillProof` schema.
365
+
110
366
  ## License
111
367
 
112
368
  Apache-2.0.