@d20dao/vrf-sdk 0.3.3 → 0.4.0

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 (21) hide show
  1. package/AGENTS.md +31 -15
  2. package/API.md +2190 -0
  3. package/BUILD-MANIFEST.json +18 -16
  4. package/CHANGELOG.md +44 -0
  5. package/PROTOCOL-PROVENANCE.json +9 -8
  6. package/README.md +157 -97
  7. package/abi/EpochEntropy.json +372 -26
  8. package/dist/abi.d.ts +292 -24
  9. package/dist/abi.js +1 -1
  10. package/dist/epoch.d.ts +42 -78
  11. package/dist/epoch.js +121 -27
  12. package/dist/index.d.ts +4 -2
  13. package/dist/index.js +2 -1
  14. package/dist/sources.js +2 -0
  15. package/dist/templates.d.ts +22 -0
  16. package/dist/templates.js +220 -0
  17. package/examples/DiceConsumer.sol +37 -29
  18. package/examples/LootDropConsumer.sol +60 -0
  19. package/examples/RaffleConsumer.sol +71 -0
  20. package/package.json +6 -2
  21. package/contracts/examples/MiningRandomnessConsumer.sol +0 -59
package/BUILD-MANIFEST.json CHANGED
@@ -2,13 +2,12 @@
2
2
  "compiler": "0.8.28+commit.7893614a.Emscripten.clang",
3
3
  "protocol": {
4
4
  "sourceRepository": "https://github.com/d20dao/keeper",
5
- "sourceCommit": "640b60cb992a7e3add1efe8e7b392341732ea004",
5
+ "sourceCommit": "de5f82eb9fc749c80e83270f57cde9908ddcf1f3",
6
6
  "note": "Current public d20dao protocol copied byte-for-byte from committed Git blobs. Operator backends, keys, test fixtures and proof generation are excluded from the package.",
7
7
  "files": {
8
8
  "LICENSE": "bfdc94eef4cfbec12a9ed47bb406c8125cf4c306facf7b8d92db58f133b1a703",
9
9
  "contracts/D20VRFConsumer.sol": "9200fcd8825756ba6978e42d94b52e82e6dea9b1ba35dc506652490194e16162",
10
- "contracts/D20VRFCoordinator.sol": "f2c17545fe39323a39aef8a4e642965f5a607ba547365da0b542b5277be4dd2c",
11
- "contracts/examples/MiningRandomnessConsumer.sol": "2f5c19d05e66bea313fff65269650fe1e3bea70bd6aa80fa3e3de8bee8c24649",
10
+ "contracts/D20VRFCoordinator.sol": "6d5dc7713d0313f8496eae1dddd6fc5626dc5b8a082fc42da6a87ce2b5d4de4f",
12
11
  "contracts/interfaces/ID20VRF.sol": "0361aee07644cbf7c2bcde8ffd9188825d5be633c4a1520169a7702a38c1bdbc",
13
12
  "contracts/libraries/D20VRFRequests.sol": "f87e66f7eb0350d9b8740f120b97085957793b826b81a0c7c80d58a3fcd92b76",
14
13
  "contracts/libraries/RandomnessMapping.sol": "00bce68c1a6d89903d72d1c3f9ee5e1a56392188ed29b6aa32ab7451ef180c91",
@@ -16,17 +15,19 @@
16
15
  "contracts/vendor/PROVENANCE.md": "e6da392378851c47574ef808c9c7e17dea50054ffd0cae7a9070f76f8eed60f2",
17
16
  "contracts/vendor/VRF.sol": "98e0345fd2dd42178cad4ad16dd8b18621112078d63d0c64839c8bd01c539350",
18
17
  "src/evidence.ts": "81b6a1446b9700ec545e794b08d356411608aa655e6030cdfabd1dfa531ef457",
19
- "src/index.ts": "6c23d8e952dfe4b7cd08cbd36f2e4bf6f434ebfc408c602038bc678b2ba4e174",
18
+ "src/index.ts": "0a791dc1d12d8f02e503f4990b057f89838f16f93bbdafc4fb3effa6917daf80",
20
19
  "src/mapping.ts": "76aa6093d55831052b56e177fc394ef6ef14183a8ab8ca6fcc2c9382efb6b83f",
21
20
  "src/replay.ts": "c97a5081e785e6a7f27987e2d4c4d9861fe8fa8cbc775b0152e337141d3d48d7",
22
- "src/sources.ts": "d8566e7809c67dc51acab3b58fc93d734d098c2eabbaf3657ac910affe12e31e",
21
+ "src/sources.ts": "8e8b50adf76f4b17d3936ffa4bb4d13e3891f6c7c40483cc9854fc28d0e88a1d",
23
22
  "src/verification.ts": "754e39554c0c432cf1404741503f66b4199b84f39003d8e42f300a7256ffaa6a",
24
- "src/epoch.ts": "41a3d60f063deccc6d19761dc63702a2fdd1efdc46f775b7202241c3eb4d1334",
25
- "contracts/EpochEntropy.sol": "bdd4f9e5dab6626572a72a0c15e73b4f3f19c6933b7a122fad237a9784fa3cbb",
26
- "contracts/D20Proxy.sol": "83dcef3b72e2a0a4809c2d8df0d083d2a0f659fe2b3b01fadb1b2eaf8afb7286"
23
+ "src/epoch.ts": "91bb0d818315dfb5841e1a0450c4b8839d6992ae7d573b33bda1f8797f071aa0",
24
+ "contracts/EpochEntropy.sol": "ece8798c2a608d20e1863debaab993a108266bd10b2f45bd762fab9f1db8243f",
25
+ "contracts/D20Proxy.sol": "83dcef3b72e2a0a4809c2d8df0d083d2a0f659fe2b3b01fadb1b2eaf8afb7286",
26
+ "contracts/libraries/DataTemplate.sol": "f0d93c2ec3bcb8cfb625001506fe24f938e6e2cfbae85632f2980d23595ed961",
27
+ "src/templates.ts": "7f74968e746461e168a863769736399d74bdab29041ab8dd1cdc0d197b927e61"
27
28
  }
28
29
  },
29
- "packageLockSha256": "968ebea1fa309fa4fb730d87937dd745f172f0eee96cefcd51e252803cdf6020",
30
+ "packageLockSha256": "39cd5746f13f589dd9145f304d2ad68c64a25fcd1a746baa7f94d52fe41238c2",
30
31
  "buildDependencies": {
31
32
  "@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol": "41a3040398d53999dea3251ff8906e11ec1a699362a1d8f4a55bfc7709cc00f3",
32
33
  "@openzeppelin/contracts/utils/ReentrancyGuard.sol": "94e409e8f6e3184236651a6cc2b1a6a3ea0f0a25eb85b71e524ad5791bb2fbc8",
@@ -56,8 +57,7 @@
56
57
  "sources": {
57
58
  "LICENSE": "bfdc94eef4cfbec12a9ed47bb406c8125cf4c306facf7b8d92db58f133b1a703",
58
59
  "contracts/D20VRFConsumer.sol": "9200fcd8825756ba6978e42d94b52e82e6dea9b1ba35dc506652490194e16162",
59
- "contracts/D20VRFCoordinator.sol": "f2c17545fe39323a39aef8a4e642965f5a607ba547365da0b542b5277be4dd2c",
60
- "contracts/examples/MiningRandomnessConsumer.sol": "2f5c19d05e66bea313fff65269650fe1e3bea70bd6aa80fa3e3de8bee8c24649",
60
+ "contracts/D20VRFCoordinator.sol": "6d5dc7713d0313f8496eae1dddd6fc5626dc5b8a082fc42da6a87ce2b5d4de4f",
61
61
  "contracts/interfaces/ID20VRF.sol": "0361aee07644cbf7c2bcde8ffd9188825d5be633c4a1520169a7702a38c1bdbc",
62
62
  "contracts/libraries/D20VRFRequests.sol": "f87e66f7eb0350d9b8740f120b97085957793b826b81a0c7c80d58a3fcd92b76",
63
63
  "contracts/libraries/RandomnessMapping.sol": "00bce68c1a6d89903d72d1c3f9ee5e1a56392188ed29b6aa32ab7451ef180c91",
@@ -65,14 +65,16 @@
65
65
  "contracts/vendor/PROVENANCE.md": "e6da392378851c47574ef808c9c7e17dea50054ffd0cae7a9070f76f8eed60f2",
66
66
  "contracts/vendor/VRF.sol": "98e0345fd2dd42178cad4ad16dd8b18621112078d63d0c64839c8bd01c539350",
67
67
  "src/evidence.ts": "81b6a1446b9700ec545e794b08d356411608aa655e6030cdfabd1dfa531ef457",
68
- "src/index.ts": "6c23d8e952dfe4b7cd08cbd36f2e4bf6f434ebfc408c602038bc678b2ba4e174",
68
+ "src/index.ts": "0a791dc1d12d8f02e503f4990b057f89838f16f93bbdafc4fb3effa6917daf80",
69
69
  "src/mapping.ts": "76aa6093d55831052b56e177fc394ef6ef14183a8ab8ca6fcc2c9382efb6b83f",
70
70
  "src/replay.ts": "c97a5081e785e6a7f27987e2d4c4d9861fe8fa8cbc775b0152e337141d3d48d7",
71
- "src/sources.ts": "d8566e7809c67dc51acab3b58fc93d734d098c2eabbaf3657ac910affe12e31e",
71
+ "src/sources.ts": "8e8b50adf76f4b17d3936ffa4bb4d13e3891f6c7c40483cc9854fc28d0e88a1d",
72
72
  "src/verification.ts": "754e39554c0c432cf1404741503f66b4199b84f39003d8e42f300a7256ffaa6a",
73
- "src/epoch.ts": "41a3d60f063deccc6d19761dc63702a2fdd1efdc46f775b7202241c3eb4d1334",
74
- "contracts/EpochEntropy.sol": "bdd4f9e5dab6626572a72a0c15e73b4f3f19c6933b7a122fad237a9784fa3cbb",
75
- "contracts/D20Proxy.sol": "83dcef3b72e2a0a4809c2d8df0d083d2a0f659fe2b3b01fadb1b2eaf8afb7286"
73
+ "src/epoch.ts": "91bb0d818315dfb5841e1a0450c4b8839d6992ae7d573b33bda1f8797f071aa0",
74
+ "contracts/EpochEntropy.sol": "ece8798c2a608d20e1863debaab993a108266bd10b2f45bd762fab9f1db8243f",
75
+ "contracts/D20Proxy.sol": "83dcef3b72e2a0a4809c2d8df0d083d2a0f659fe2b3b01fadb1b2eaf8afb7286",
76
+ "contracts/libraries/DataTemplate.sol": "f0d93c2ec3bcb8cfb625001506fe24f938e6e2cfbae85632f2980d23595ed961",
77
+ "src/templates.ts": "7f74968e746461e168a863769736399d74bdab29041ab8dd1cdc0d197b927e61"
76
78
  },
77
79
  "packageSources": {
78
80
  "src/fees.ts": "836f6a6e14d638876a4ceca8f3369577edb5d242096b420606fb69c74bb7dcae"
package/CHANGELOG.md ADDED
@@ -0,0 +1,44 @@
1
+ # Changelog
2
+
3
+ ## 0.4.0
4
+
5
+ Both Arc networks run the upgraded contracts. The proxy addresses are unchanged, so nothing in an existing
6
+ integration has to move; the coordinator interface a consumer calls is the same as in 0.3.4.
7
+
8
+ ### Protocol
9
+
10
+ - **The epoch source catalog is an on-chain recipe registry.** A recipe is a canonical request, a data template
11
+ that fixes the exact signed bytes the registry accepts, and the gateway body. `registerRecipe` appends an id
12
+ and a registered recipe never changes. Five sources are active: Hyperliquid BTC day volume, dRPC Ethereum
13
+ block hash, TickerLayer BTCUSD, Nodary ETH/USD and dRPC Base block hash. Arc Testnet draws from them
14
+ from epoch 966 and Arc Mainnet from epoch 848.
15
+ - **The keeper share follows the wallet that serves the request.** At proof acceptance `keeperFeeBps` of the
16
+ escrowed fee goes to the submitting wallet when the registry authorizes it — the committer or an allowed
17
+ backup committer — and to `committer()` for any other submitter. Backup committers let a second keeper take
18
+ over. Consumers see no API change.
19
+ - New implementations behind the unchanged proxies on both chains: registry
20
+ `0xd20dA048C969e5aDcC703Dfdf8220cc9dCB2f865`, coordinator `0xd20da0DADa4352A1a9722be43a2D85923443458c`.
21
+
22
+ ### SDK
23
+
24
+ - New epoch helpers for the registry: `BUILTIN_EPOCH_RECIPES`, `readEpochRecipes`, `resolveEpochCatalog` and
25
+ `MAX_ATTESTATION_AGE`, plus the data-template helpers `encodeDataTemplate`, `decodeDataTemplate`,
26
+ `matchesDataTemplate`, `isValidDataTemplate` and `validateDataTemplate` on the root entry point.
27
+ - `epochEntropyAbi` and `abi/EpochEntropy.json` cover `registerRecipe`, `getRecipe`, `recipeCount`,
28
+ `scheduleCatalog`, `catalogAt`, `setBackupCommitter`, `isBackupCommitter` and `isAuthorizedCommitter`. The
29
+ four-signer catalog views (`signersAt`, `catalogHashAt`, `anuSigner`) are gone.
30
+ - `replayEpochCommitment` checks the committed packet against the recipe's canonical request and data template,
31
+ and derives the fallback attempt from the committed source.
32
+ - Three examples replace the previous two. `examples/DiceConsumer.sol` is a dice roll,
33
+ `examples/RaffleConsumer.sol` draws one winner from a frozen list and shows the `_onRefund` hook, and
34
+ `examples/LootDropConsumer.sol` is a weighted drop. Each is self-contained and sixty to seventy lines.
35
+ - **Removed:** `contracts/examples/MiningRandomnessConsumer.sol`. It was an abstract building block for one
36
+ application, not something to copy on a first day. Nothing else imported it; the payment pattern it showed is
37
+ in [Best practices](README.md#best-practices) and the change-returning variant is in `DiceConsumer`.
38
+ - New [Best practices](README.md#best-practices) section in the README, reflected in `AGENTS.md`.
39
+ - Vendored protocol re-pinned; `PROTOCOL-PROVENANCE.json` names the commit and the SHA-256 of every file.
40
+
41
+ ## 0.3.4 and earlier
42
+
43
+ Base-fee request pricing (`quoteFee`, `quoteFeeAt`, `quoteRequestFee`) with overpayment credit, epoch source
44
+ fallback, the generated `API.md` reference, the Arc Mainnet deployment and the 50% keeper share.
package/PROTOCOL-PROVENANCE.json CHANGED
@@ -1,12 +1,11 @@
1
1
  {
2
2
  "sourceRepository": "https://github.com/d20dao/keeper",
3
- "sourceCommit": "640b60cb992a7e3add1efe8e7b392341732ea004",
3
+ "sourceCommit": "de5f82eb9fc749c80e83270f57cde9908ddcf1f3",
4
4
  "note": "Current public d20dao protocol copied byte-for-byte from committed Git blobs. Operator backends, keys, test fixtures and proof generation are excluded from the package.",
5
5
  "files": {
6
6
  "LICENSE": "bfdc94eef4cfbec12a9ed47bb406c8125cf4c306facf7b8d92db58f133b1a703",
7
7
  "contracts/D20VRFConsumer.sol": "9200fcd8825756ba6978e42d94b52e82e6dea9b1ba35dc506652490194e16162",
8
- "contracts/D20VRFCoordinator.sol": "f2c17545fe39323a39aef8a4e642965f5a607ba547365da0b542b5277be4dd2c",
9
- "contracts/examples/MiningRandomnessConsumer.sol": "2f5c19d05e66bea313fff65269650fe1e3bea70bd6aa80fa3e3de8bee8c24649",
8
+ "contracts/D20VRFCoordinator.sol": "6d5dc7713d0313f8496eae1dddd6fc5626dc5b8a082fc42da6a87ce2b5d4de4f",
10
9
  "contracts/interfaces/ID20VRF.sol": "0361aee07644cbf7c2bcde8ffd9188825d5be633c4a1520169a7702a38c1bdbc",
11
10
  "contracts/libraries/D20VRFRequests.sol": "f87e66f7eb0350d9b8740f120b97085957793b826b81a0c7c80d58a3fcd92b76",
12
11
  "contracts/libraries/RandomnessMapping.sol": "00bce68c1a6d89903d72d1c3f9ee5e1a56392188ed29b6aa32ab7451ef180c91",
@@ -14,13 +13,15 @@
14
13
  "contracts/vendor/PROVENANCE.md": "e6da392378851c47574ef808c9c7e17dea50054ffd0cae7a9070f76f8eed60f2",
15
14
  "contracts/vendor/VRF.sol": "98e0345fd2dd42178cad4ad16dd8b18621112078d63d0c64839c8bd01c539350",
16
15
  "src/evidence.ts": "81b6a1446b9700ec545e794b08d356411608aa655e6030cdfabd1dfa531ef457",
17
- "src/index.ts": "6c23d8e952dfe4b7cd08cbd36f2e4bf6f434ebfc408c602038bc678b2ba4e174",
16
+ "src/index.ts": "0a791dc1d12d8f02e503f4990b057f89838f16f93bbdafc4fb3effa6917daf80",
18
17
  "src/mapping.ts": "76aa6093d55831052b56e177fc394ef6ef14183a8ab8ca6fcc2c9382efb6b83f",
19
18
  "src/replay.ts": "c97a5081e785e6a7f27987e2d4c4d9861fe8fa8cbc775b0152e337141d3d48d7",
20
- "src/sources.ts": "d8566e7809c67dc51acab3b58fc93d734d098c2eabbaf3657ac910affe12e31e",
19
+ "src/sources.ts": "8e8b50adf76f4b17d3936ffa4bb4d13e3891f6c7c40483cc9854fc28d0e88a1d",
21
20
  "src/verification.ts": "754e39554c0c432cf1404741503f66b4199b84f39003d8e42f300a7256ffaa6a",
22
- "src/epoch.ts": "41a3d60f063deccc6d19761dc63702a2fdd1efdc46f775b7202241c3eb4d1334",
23
- "contracts/EpochEntropy.sol": "bdd4f9e5dab6626572a72a0c15e73b4f3f19c6933b7a122fad237a9784fa3cbb",
24
- "contracts/D20Proxy.sol": "83dcef3b72e2a0a4809c2d8df0d083d2a0f659fe2b3b01fadb1b2eaf8afb7286"
21
+ "src/epoch.ts": "91bb0d818315dfb5841e1a0450c4b8839d6992ae7d573b33bda1f8797f071aa0",
22
+ "contracts/EpochEntropy.sol": "ece8798c2a608d20e1863debaab993a108266bd10b2f45bd762fab9f1db8243f",
23
+ "contracts/D20Proxy.sol": "83dcef3b72e2a0a4809c2d8df0d083d2a0f659fe2b3b01fadb1b2eaf8afb7286",
24
+ "contracts/libraries/DataTemplate.sol": "f0d93c2ec3bcb8cfb625001506fe24f938e6e2cfbae85632f2980d23595ed961",
25
+ "src/templates.ts": "7f74968e746461e168a863769736399d74bdab29041ab8dd1cdc0d197b927e61"
25
26
  }
26
27
  }