@cancore/contracts 0.1.0 → 0.2.0-rc.3

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 (47) hide show
  1. package/README.md +168 -9
  2. package/dist/abi.d.ts +6086 -1675
  3. package/dist/abi.js +1 -1
  4. package/dist/chunk-NV5IUURP.js +9252 -0
  5. package/dist/chunk-NV5IUURP.js.map +1 -0
  6. package/dist/{chunk-CIBYXHSX.js → chunk-VODZRADO.js} +2 -2
  7. package/dist/chunk-VODZRADO.js.map +1 -0
  8. package/dist/index.d.ts +849 -28
  9. package/dist/index.js +2065 -16
  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 +1050 -0
  27. package/spec/protocol/messages.schema.json +414 -0
  28. package/spec/protocol/records.schema.json +93 -0
  29. package/spec/protocol/rest.schema.json +115 -0
  30. package/spec/protocol/typed-data/FillerAuth.json +58 -0
  31. package/spec/protocol/typed-data/FillerQuote.json +75 -0
  32. package/spec/protocol/typed-data/GatewayMessage.json +90 -0
  33. package/spec/protocol/typed-data/StakeBinding.json +75 -0
  34. package/spec/protocol/typed-data/TicketIntent.json +65 -0
  35. package/spec/protocol/typed-data/TicketReceipt.json +51 -0
  36. package/spec/protocol/vectors/draw.json +61 -0
  37. package/spec/protocol/vectors/jcs.json +59 -0
  38. package/spec/protocol/vectors/messages.json +343 -0
  39. package/spec/protocol/vectors/records.json +81 -0
  40. package/spec/typed-data/FillProof.json +199 -0
  41. package/spec/typed-data/FillTicket.json +83 -0
  42. package/spec/typed-data/Order.json +141 -0
  43. package/spec/typed-data/Quote.json +69 -0
  44. package/spec/vectors/canton-order.json +67 -0
  45. package/dist/chunk-CIBYXHSX.js.map +0 -1
  46. package/dist/chunk-ZSX67S72.js +0 -3423
  47. 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` / `requestIdHash`, `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` / `FillProof`, `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,130 @@ 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.
70
+
71
+ ```ts
72
+ import { FILL_PROOF_TYPES, fillProofDomain, PROOF_KIND_ATTESTATION } from '@cancore/contracts';
73
+
74
+ const signature = await wallet.signTypedData({
75
+ domain: fillProofDomain(sourceChainId, sourceRouter),
76
+ types: FILL_PROOF_TYPES,
77
+ primaryType: 'FillProof',
78
+ message: proof, // setId: attestationSetFor(orderHash), never currentSetId
79
+ });
80
+ ```
81
+
82
+ This repository keeps golden vectors for the schema in `spec/typed-data/FillProof.json` (shipped
83
+ in the package since 0.2.0, under `@cancore/contracts/spec/*`). `evm-contracts` checks every vector against the router's own
84
+ `hashFillProof`, and this package's test checks the same file with an encoder of its own: a
85
+ field changed there fails there at once, and here after the next `npm run sync`. The schema is
86
+ synced like the ABIs.
87
+
88
+ ## Filler protocol v1 (RC)
89
+
90
+ The wire protocol between a taker and the Cancore filler gateway, frozen as a release
91
+ candidate in `0.2.0-rc.1` (npm dist-tag `next`). In `0.x` protocol v1 is the `0.2.x` line; a
92
+ breaking protocol change is `0.3`.
93
+
94
+ ```ts
95
+ import {
96
+ FILLER_PROTOCOL_DOMAIN, TICKET_INTENT_TYPES, hashTypedData, gatewayBodyHash, GATEWAY_MESSAGE_TYPES,
97
+ } from '@cancore/contracts';
98
+
99
+ // what the filler address signs to take an offered ticket
100
+ const digest = hashTypedData({
101
+ domain: FILLER_PROTOCOL_DOMAIN,
102
+ types: TICKET_INTENT_TYPES,
103
+ primaryType: 'TicketIntent',
104
+ message: { orderHash, attempt, validFrom, validUntil },
105
+ });
106
+
107
+ // what every S→F frame's `sig` is over: GatewayMessage{bodyHash} in the same domain
108
+ const bodyHash = gatewayBodyHash(frame); // keccak256(JCS(frame without sig))
109
+ ```
110
+
111
+ `hashTypedData` encodes flat structs (address, bool, bytes, bytesN, string, uintN) and throws on
112
+ anything else; it takes wire values as they come — decimal strings, numbers or bigints. There
113
+ is no signing in this package: hand the digest to your own secp256k1 key.
114
+
115
+ | Types | Domain | Status |
116
+ | --- | --- | --- |
117
+ | `FillerQuote`, `TicketIntent`, `TicketReceipt`, `StakeBinding`, `FillerAuth`, `GatewayMessage` | `CancoreFillerProtocol` v1 | frozen v1 (RC) — vectors in `spec/protocol/typed-data/` |
118
+ | `Order` (11 fields, with `createdAt`), `Quote` | `CancoreRouter` v1, source router | router code; provisional copies in `spec/typed-data/` until evm-contracts publishes them |
119
+ | `FillTicket` | `CancoreFillTicket` v1 | router code; provisional copy, as above |
120
+ | `FillProof` | `CancoreRouter` v1, source router | synced from evm-contracts (above) |
121
+
122
+ Golden vectors are generated with ethers by `scripts/gen-protocol-vectors.mjs` from the literal
123
+ inputs in `scripts/protocol-fixtures.mjs`, and checked by this package's own encoder too. The
124
+ `canton` Order vector equals `spec/vectors/canton-order.json`, a byte copy of
125
+ `evm-contracts/test/vectors/canton-order.json` at `f936594`, which the router's test pins.
126
+ `spec/protocol/vectors/jcs.json` holds RFC 8785 cases and `draw.json` the draw of
127
+ auction-and-draw §3.7 (r = 417828, acme-markets) plus the test-kit fixture draw, both on real
128
+ drand quicknet rounds.
129
+
130
+ ### Schemas, AsyncAPI, examples
131
+
132
+ | File (`@cancore/contracts/spec/protocol/…`) | Holds |
133
+ | --- | --- |
134
+ | `messages.schema.json` | one `$def` per WebSocket frame type (22), `x-direction` S2F / F2S / both, and the primitives they share |
135
+ | `rest.schema.json` | REST fallback bodies; `x-endpoints` (method, path, auth, request/response), `x-error-status` |
136
+ | `records.schema.json` | the draw record, the epoch record, `GET /v1/gateway` |
137
+ | `asyncapi.json` | AsyncAPI 3.0: channel `/v1`, the gateway's send/receive operations, examples |
138
+ | `vectors/messages.json`, `vectors/records.json` | valid example frames and fixture records (hashes real, `sig` a placeholder: r = s = 0, v = 27) |
139
+
140
+ The same objects are exported as `PROTOCOL_SCHEMAS`, `ASYNCAPI`, `MESSAGE_DIRECTIONS` and
141
+ `REST_ENDPOINTS`, with TypeScript shapes of every frame (`TicketOffer`, `QuoteAck`, …) and the
142
+ enums (`DECLINE_REASONS`, `ERROR_CODES`, …) a test holds to the schemas.
143
+
144
+ ```ts
145
+ import Ajv2020 from 'ajv/dist/2020';
146
+ import { PROTOCOL_SCHEMAS, SCHEMA_VOCABULARY, messageSchemaRef } from '@cancore/contracts';
147
+
148
+ const ajv = new Ajv2020({ strict: true });
149
+ ajv.addVocabulary([...SCHEMA_VOCABULARY]);
150
+ for (const schema of Object.values(PROTOCOL_SCHEMAS)) ajv.addSchema(schema);
151
+ ajv.validate(messageSchemaRef(frame.type, 'S2F'), frame); // errors name the field: instancePath "/amountOut"
152
+ ```
153
+
154
+ The schemas describe what a v1 **sender** emits: lowercase hex, uint64 and wider as decimal
155
+ strings, gateway times in milliseconds, every S→F frame with `fillerId`, `sentAt` and `sig`. No
156
+ object is closed: a receiver ignores unknown fields and a taker ignores unknown S→F types
157
+ (V-2), so check a frame of an unknown type against `s2fEnvelope` and skip it. Every enum is
158
+ open the same way: the known values, or any UPPER_SNAKE value added within v1, which a receiver
159
+ treats as `OTHER`/generic; a `ticket.issued` of an unknown `form` is checked on its common fields
160
+ only. `ping`/`pong` go both ways: the gateway's copy is signed like every S→F frame
161
+ (`pingS2F`), the taker's is not (`pingF2S`); the second argument of `messageSchemaRef` picks one.
162
+ `scripts/gen-protocol-docs.mjs` derives the examples, records and the AsyncAPI document from
163
+ the schemas and the vectors.
164
+
165
+ `FILLER_GATEWAYS` is where the gateway key and the ticket signers of each environment are
166
+ published. It is empty in the RC: no gateway key exists yet.
167
+
42
168
  ## Reverts
43
169
 
44
170
  ```ts
@@ -62,9 +188,14 @@ const { htlc, htlcBlock } = deploymentOf('mainnet', 'arbitrum')!;
62
188
  Three environments, three independent deployments: what is on Sepolia for the dev stand is
63
189
  not what is on Sepolia for testnet. `htlcBlock` is the floor for an event scan.
64
190
 
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.
191
+ `BYTECODE_HASHES` pins the build each release was made from, as `evm-contracts` records it in
192
+ `scripts/tools/check-bytecode-match.mjs`: `bytecodeHash` and `deployedBytecodeHash` are sha256
193
+ of the UTF-8 text of the artifact's `0x`-prefixed hex (creation and runtime code) — not
194
+ keccak256, and not of the bytes — and `bytecodeLength` / `deployedBytecodeLength` are the length
195
+ of that text, `0x` included. It is not a hash of `eth_getCode`: a contract with
196
+ immutables (`CancoreRouter`, `FeeVault`) never matches one, so checking a live deployment
197
+ against it means rebuilding the release, not hashing the address. `CONTRACTS_RELEASE` names the
198
+ release.
68
199
 
69
200
  ## The FeeClaim voucher
70
201
 
@@ -102,11 +233,39 @@ added.
102
233
  EVM_CONTRACTS_DIR=../evm-contracts npm run sync # then review the diff and release
103
234
  ```
104
235
 
236
+ `npm run sync` is two scripts: `scripts/sync.mjs` (ABIs, error tables, release identity) and
237
+ `scripts/sync-typed-data.mjs` (`abi/typed-data/*.json`). Until evm-contracts publishes
238
+ `abi/typed-data/` the second one fails; run the first one alone:
239
+
240
+ ```bash
241
+ EVM_CONTRACTS_DIR=../evm-contracts node scripts/sync.mjs
242
+ ```
243
+
244
+ It reads `abi/*.json` except the two manifests (`bytecode-hashes.json`, `versions.json`) and
245
+ `vendor/*.json` (the `.abi` field), and refuses to run when `spec/abi/` holds a snapshot the
246
+ source no longer has — dropping a published ABI is a decision, not a side effect of a sync.
247
+
105
248
  A contract change is a release of this package. `CONTRACTS_RELEASE.version` says which
106
249
  `evm-contracts` version the data was taken from.
107
250
 
108
251
  Full documentation: <https://docs.cancore.io/sdk/contracts>
109
252
 
253
+ ## Changes
254
+
255
+ - `0.2.0-rc.3` — adds the `CNRXStaking` and `PointsClaim` ABIs with their error tables
256
+ (`CNRX_STAKING_ABI`, `CNRX_STAKING_ERRORS`, `POINTS_CLAIM_ABI`, `POINTS_CLAIM_ERRORS`). The
257
+ generator now splits an acronym of two or more capitals from the word after it, which renames
258
+ nothing already exported. Additive only. Neither contract has an address in `DEPLOYMENTS`
259
+ yet; addresses come in a later release.
260
+ - `0.2.0-rc.2` — adds the `CancoreRouter`, `ICancoreRouter` and `AttestorSet` ABIs with their error
261
+ tables; `FeeVault` gains the `TransferFailed()` error and `IPermit2` gains
262
+ `permitWitnessTransferFrom`; CNRX and IBurnMintERC20 are now read from `evm-contracts/vendor/`.
263
+ Additive only. Documentation correction: `BYTECODE_HASHES` values have always been sha256 of
264
+ the artifact's hex text, never keccak256 or a hash of `eth_getCode`, as the `0.1.x` README
265
+ said; the values' meaning is unchanged.
266
+ - `0.2.0-rc.1` — filler protocol v1 release candidate: EIP-712 types, hashing helpers, JSON
267
+ Schemas, AsyncAPI, golden vectors; the `FillProof` schema.
268
+
110
269
  ## License
111
270
 
112
271
  Apache-2.0.