@aztec/ethereum 3.0.3 → 3.9.9-nightly.20260312

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 (175) hide show
  1. package/dest/client.js +6 -2
  2. package/dest/config.d.ts +19 -27
  3. package/dest/config.d.ts.map +1 -1
  4. package/dest/config.js +60 -55
  5. package/dest/contracts/empire_base.d.ts +4 -1
  6. package/dest/contracts/empire_base.d.ts.map +1 -1
  7. package/dest/contracts/empire_slashing_proposer.d.ts +4 -1
  8. package/dest/contracts/empire_slashing_proposer.d.ts.map +1 -1
  9. package/dest/contracts/empire_slashing_proposer.js +31 -15
  10. package/dest/contracts/fee_asset_handler.d.ts +6 -5
  11. package/dest/contracts/fee_asset_handler.d.ts.map +1 -1
  12. package/dest/contracts/fee_asset_handler.js +11 -9
  13. package/dest/contracts/fee_asset_price_oracle.d.ts +101 -0
  14. package/dest/contracts/fee_asset_price_oracle.d.ts.map +1 -0
  15. package/dest/contracts/fee_asset_price_oracle.js +651 -0
  16. package/dest/contracts/governance.d.ts +3 -1
  17. package/dest/contracts/governance.d.ts.map +1 -1
  18. package/dest/contracts/governance.js +14 -4
  19. package/dest/contracts/governance_proposer.d.ts +4 -1
  20. package/dest/contracts/governance_proposer.d.ts.map +1 -1
  21. package/dest/contracts/governance_proposer.js +404 -9
  22. package/dest/contracts/inbox.d.ts +22 -1
  23. package/dest/contracts/inbox.d.ts.map +1 -1
  24. package/dest/contracts/inbox.js +36 -1
  25. package/dest/contracts/index.d.ts +4 -1
  26. package/dest/contracts/index.d.ts.map +1 -1
  27. package/dest/contracts/index.js +3 -0
  28. package/dest/contracts/log.d.ts +13 -0
  29. package/dest/contracts/log.d.ts.map +1 -0
  30. package/dest/contracts/log.js +1 -0
  31. package/dest/contracts/multicall.d.ts +1 -1
  32. package/dest/contracts/multicall.d.ts.map +1 -1
  33. package/dest/contracts/multicall.js +2 -1
  34. package/dest/contracts/outbox.d.ts +41 -0
  35. package/dest/contracts/outbox.d.ts.map +1 -0
  36. package/dest/contracts/outbox.js +86 -0
  37. package/dest/contracts/registry.d.ts +3 -1
  38. package/dest/contracts/registry.d.ts.map +1 -1
  39. package/dest/contracts/registry.js +30 -1
  40. package/dest/contracts/rollup.d.ts +163 -81
  41. package/dest/contracts/rollup.d.ts.map +1 -1
  42. package/dest/contracts/rollup.js +703 -132
  43. package/dest/contracts/tally_slashing_proposer.d.ts +1 -1
  44. package/dest/contracts/tally_slashing_proposer.d.ts.map +1 -1
  45. package/dest/contracts/tally_slashing_proposer.js +8 -1
  46. package/dest/deploy_aztec_l1_contracts.d.ts +18 -4
  47. package/dest/deploy_aztec_l1_contracts.d.ts.map +1 -1
  48. package/dest/deploy_aztec_l1_contracts.js +117 -35
  49. package/dest/deploy_l1_contract.js +3 -3
  50. package/dest/generated/l1-contracts-defaults.d.ts +30 -0
  51. package/dest/generated/l1-contracts-defaults.d.ts.map +1 -0
  52. package/dest/generated/l1-contracts-defaults.js +30 -0
  53. package/dest/l1_artifacts.d.ts +5975 -1575
  54. package/dest/l1_artifacts.d.ts.map +1 -1
  55. package/dest/l1_contract_addresses.d.ts +1 -1
  56. package/dest/l1_contract_addresses.d.ts.map +1 -1
  57. package/dest/l1_contract_addresses.js +3 -3
  58. package/dest/l1_tx_utils/config.d.ts +7 -1
  59. package/dest/l1_tx_utils/config.d.ts.map +1 -1
  60. package/dest/l1_tx_utils/config.js +14 -1
  61. package/dest/l1_tx_utils/constants.d.ts +8 -2
  62. package/dest/l1_tx_utils/constants.d.ts.map +1 -1
  63. package/dest/l1_tx_utils/constants.js +27 -2
  64. package/dest/l1_tx_utils/factory.d.ts +18 -10
  65. package/dest/l1_tx_utils/factory.d.ts.map +1 -1
  66. package/dest/l1_tx_utils/factory.js +17 -7
  67. package/dest/l1_tx_utils/fee-strategies/index.d.ts +10 -0
  68. package/dest/l1_tx_utils/fee-strategies/index.d.ts.map +1 -0
  69. package/dest/l1_tx_utils/fee-strategies/index.js +12 -0
  70. package/dest/l1_tx_utils/fee-strategies/p75_competitive.d.ts +8 -0
  71. package/dest/l1_tx_utils/fee-strategies/p75_competitive.d.ts.map +1 -0
  72. package/dest/l1_tx_utils/fee-strategies/p75_competitive.js +129 -0
  73. package/dest/l1_tx_utils/fee-strategies/p75_competitive_blob_txs_only.d.ts +23 -0
  74. package/dest/l1_tx_utils/fee-strategies/p75_competitive_blob_txs_only.d.ts.map +1 -0
  75. package/dest/l1_tx_utils/fee-strategies/p75_competitive_blob_txs_only.js +191 -0
  76. package/dest/l1_tx_utils/fee-strategies/types.d.ts +51 -0
  77. package/dest/l1_tx_utils/fee-strategies/types.d.ts.map +1 -0
  78. package/dest/l1_tx_utils/fee-strategies/types.js +3 -0
  79. package/dest/l1_tx_utils/forwarder_l1_tx_utils.d.ts +15 -15
  80. package/dest/l1_tx_utils/forwarder_l1_tx_utils.d.ts.map +1 -1
  81. package/dest/l1_tx_utils/forwarder_l1_tx_utils.js +9 -15
  82. package/dest/l1_tx_utils/index-blobs.d.ts +3 -3
  83. package/dest/l1_tx_utils/index-blobs.d.ts.map +1 -1
  84. package/dest/l1_tx_utils/index-blobs.js +2 -2
  85. package/dest/l1_tx_utils/index.d.ts +4 -1
  86. package/dest/l1_tx_utils/index.d.ts.map +1 -1
  87. package/dest/l1_tx_utils/index.js +3 -0
  88. package/dest/l1_tx_utils/l1_fee_analyzer.d.ts +233 -0
  89. package/dest/l1_tx_utils/l1_fee_analyzer.d.ts.map +1 -0
  90. package/dest/l1_tx_utils/l1_fee_analyzer.js +506 -0
  91. package/dest/l1_tx_utils/l1_tx_utils.d.ts +18 -7
  92. package/dest/l1_tx_utils/l1_tx_utils.d.ts.map +1 -1
  93. package/dest/l1_tx_utils/l1_tx_utils.js +58 -42
  94. package/dest/l1_tx_utils/readonly_l1_tx_utils.d.ts +4 -15
  95. package/dest/l1_tx_utils/readonly_l1_tx_utils.d.ts.map +1 -1
  96. package/dest/l1_tx_utils/readonly_l1_tx_utils.js +43 -147
  97. package/dest/l1_tx_utils/tx_delayer.d.ts +56 -0
  98. package/dest/l1_tx_utils/tx_delayer.d.ts.map +1 -0
  99. package/dest/{test → l1_tx_utils}/tx_delayer.js +62 -34
  100. package/dest/publisher_manager.d.ts +3 -2
  101. package/dest/publisher_manager.d.ts.map +1 -1
  102. package/dest/publisher_manager.js +2 -2
  103. package/dest/queries.d.ts +2 -2
  104. package/dest/queries.d.ts.map +1 -1
  105. package/dest/queries.js +12 -4
  106. package/dest/test/chain_monitor.js +1 -2
  107. package/dest/test/eth_cheat_codes.d.ts +13 -1
  108. package/dest/test/eth_cheat_codes.d.ts.map +1 -1
  109. package/dest/test/eth_cheat_codes.js +3 -1
  110. package/dest/test/index.d.ts +1 -3
  111. package/dest/test/index.d.ts.map +1 -1
  112. package/dest/test/index.js +0 -2
  113. package/dest/test/rollup_cheat_codes.d.ts +5 -2
  114. package/dest/test/rollup_cheat_codes.d.ts.map +1 -1
  115. package/dest/test/rollup_cheat_codes.js +22 -3
  116. package/dest/test/start_anvil.js +1 -1
  117. package/dest/test/upgrade_utils.js +2 -2
  118. package/dest/utils.d.ts +15 -2
  119. package/dest/utils.d.ts.map +1 -1
  120. package/dest/utils.js +64 -0
  121. package/package.json +9 -7
  122. package/src/client.ts +2 -2
  123. package/src/config.ts +76 -54
  124. package/src/contracts/README.md +157 -0
  125. package/src/contracts/empire_base.ts +3 -1
  126. package/src/contracts/empire_slashing_proposer.ts +28 -28
  127. package/src/contracts/fee_asset_handler.ts +10 -7
  128. package/src/contracts/fee_asset_price_oracle.ts +280 -0
  129. package/src/contracts/governance.ts +13 -4
  130. package/src/contracts/governance_proposer.ts +16 -2
  131. package/src/contracts/inbox.ts +53 -1
  132. package/src/contracts/index.ts +3 -0
  133. package/src/contracts/log.ts +13 -0
  134. package/src/contracts/multicall.ts +5 -2
  135. package/src/contracts/outbox.ts +98 -0
  136. package/src/contracts/registry.ts +31 -1
  137. package/src/contracts/rollup.ts +382 -94
  138. package/src/contracts/tally_slashing_proposer.ts +5 -1
  139. package/src/deploy_aztec_l1_contracts.ts +147 -44
  140. package/src/deploy_l1_contract.ts +3 -3
  141. package/src/generated/l1-contracts-defaults.ts +32 -0
  142. package/src/l1_contract_addresses.ts +22 -20
  143. package/src/l1_tx_utils/config.ts +20 -0
  144. package/src/l1_tx_utils/constants.ts +13 -2
  145. package/src/l1_tx_utils/factory.ts +31 -31
  146. package/src/l1_tx_utils/fee-strategies/index.ts +22 -0
  147. package/src/l1_tx_utils/fee-strategies/p75_competitive.ts +163 -0
  148. package/src/l1_tx_utils/fee-strategies/p75_competitive_blob_txs_only.ts +245 -0
  149. package/src/l1_tx_utils/fee-strategies/types.ts +56 -0
  150. package/src/l1_tx_utils/forwarder_l1_tx_utils.ts +43 -54
  151. package/src/l1_tx_utils/index-blobs.ts +2 -2
  152. package/src/l1_tx_utils/index.ts +3 -0
  153. package/src/l1_tx_utils/l1_fee_analyzer.ts +803 -0
  154. package/src/l1_tx_utils/l1_tx_utils.ts +60 -32
  155. package/src/l1_tx_utils/readonly_l1_tx_utils.ts +56 -190
  156. package/src/{test → l1_tx_utils}/tx_delayer.ts +78 -50
  157. package/src/publisher_manager.ts +4 -2
  158. package/src/queries.ts +11 -3
  159. package/src/test/chain_monitor.ts +1 -1
  160. package/src/test/eth_cheat_codes.ts +1 -1
  161. package/src/test/index.ts +0 -2
  162. package/src/test/rollup_cheat_codes.ts +22 -4
  163. package/src/test/start_anvil.ts +1 -1
  164. package/src/test/upgrade_utils.ts +2 -2
  165. package/src/utils.ts +82 -0
  166. package/dest/l1_tx_utils/l1_tx_utils_with_blobs.d.ts +0 -26
  167. package/dest/l1_tx_utils/l1_tx_utils_with_blobs.d.ts.map +0 -1
  168. package/dest/l1_tx_utils/l1_tx_utils_with_blobs.js +0 -26
  169. package/dest/test/delayed_tx_utils.d.ts +0 -13
  170. package/dest/test/delayed_tx_utils.d.ts.map +0 -1
  171. package/dest/test/delayed_tx_utils.js +0 -28
  172. package/dest/test/tx_delayer.d.ts +0 -36
  173. package/dest/test/tx_delayer.d.ts.map +0 -1
  174. package/src/l1_tx_utils/l1_tx_utils_with_blobs.ts +0 -77
  175. package/src/test/delayed_tx_utils.ts +0 -52
@@ -1 +1 @@
1
- {"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,gCAAgC,CAAC;AACzD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAGpD,OAAO,EACL,KAAK,GAAG,EAER,KAAK,iBAAiB,EAEtB,KAAK,wBAAwB,EAC7B,KAAK,GAAG,EACR,KAAK,GAAG,EAGT,MAAM,MAAM,CAAC;AAEd,MAAM,WAAW,OAAO;IACtB,WAAW,EAAE,EAAE,CAAC;IAChB,WAAW,EAAE,EAAE,CAAC;IAChB,WAAW,EAAE,GAAG,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,YAAY,CAAC,EAAE,GAAG,EAAE,CAAC;IAErB,YAAY,OAAO,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,GAAG,EAAE,EAIhD;CACF;AAED,wBAAgB,YAAY,CAC1B,KAAK,CAAC,IAAI,SAAS,GAAG,GAAG,SAAS,OAAO,EAAE,EAC3C,UAAU,SAAS,iBAAiB,CAAC,IAAI,CAAC,EAC1C,UAAU,GAAG,wBAAwB,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,EAE/E,IAAI,EAAE,GAAG,EAAE,EACX,OAAO,EAAE,GAAG,EACZ,GAAG,EAAE,IAAI,EACT,SAAS,EAAE,UAAU,EACrB,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,OAAO,EACrC,MAAM,CAAC,EAAE,MAAM,GACd,UAAU,CAMZ;AAED,wBAAgB,eAAe,CAC7B,KAAK,CAAC,IAAI,SAAS,GAAG,GAAG,SAAS,OAAO,EAAE,EAC3C,UAAU,SAAS,iBAAiB,CAAC,IAAI,CAAC,EAC1C,UAAU,GAAG,wBAAwB,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,EAE/E,IAAI,EAAE,GAAG,EAAE,EACX,OAAO,EAAE,GAAG,EACZ,GAAG,EAAE,IAAI,EACT,SAAS,EAAE,UAAU,EACrB,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,OAAO,EACrC,MAAM,CAAC,EAAE,MAAM,GACd,UAAU,GAAG,SAAS,CAgBxB;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,GAAG,OAW7C;AA0BD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,GAAE,GAAe,GAAG,kBAAkB,CAwEpF;AAyBD,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,GAAG,sBAa7C"}
1
+ {"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,gCAAgC,CAAC;AACzD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAGpD,OAAO,EACL,KAAK,GAAG,EAGR,KAAK,iBAAiB,EAEtB,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,EACzB,KAAK,GAAG,EACR,KAAK,GAAG,EAGT,MAAM,MAAM,CAAC;AAGd,MAAM,WAAW,OAAO;IACtB,WAAW,EAAE,EAAE,CAAC;IAChB,WAAW,EAAE,EAAE,CAAC;IAChB,WAAW,EAAE,GAAG,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,YAAY,CAAC,EAAE,GAAG,EAAE,CAAC;IAErB,YAAY,OAAO,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,GAAG,EAAE,EAIhD;CACF;AAED,wBAAgB,YAAY,CAC1B,KAAK,CAAC,IAAI,SAAS,GAAG,GAAG,SAAS,OAAO,EAAE,EAC3C,UAAU,SAAS,iBAAiB,CAAC,IAAI,CAAC,EAC1C,UAAU,GAAG,wBAAwB,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,EAE/E,IAAI,EAAE,GAAG,EAAE,EACX,OAAO,EAAE,GAAG,EACZ,GAAG,EAAE,IAAI,EACT,SAAS,EAAE,UAAU,EACrB,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,OAAO,EACrC,MAAM,CAAC,EAAE,MAAM,GACd,UAAU,CAMZ;AAED,wBAAgB,eAAe,CAC7B,KAAK,CAAC,IAAI,SAAS,GAAG,GAAG,SAAS,OAAO,EAAE,EAC3C,UAAU,SAAS,iBAAiB,CAAC,IAAI,CAAC,EAC1C,UAAU,GAAG,wBAAwB,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,EAE/E,IAAI,EAAE,GAAG,EAAE,EACX,OAAO,EAAE,GAAG,EACZ,GAAG,EAAE,IAAI,EACT,SAAS,EAAE,UAAU,EACrB,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,OAAO,EACrC,MAAM,CAAC,EAAE,MAAM,GACd,UAAU,GAAG,SAAS,CAgBxB;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,GAAG,OAW7C;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,GAAG,CAe1C;AA4DD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,GAAE,GAAe,GAAG,kBAAkB,CAwEpF;AAyBD,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,GAAG,sBAa7C;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,oBAAoB,GAAG,EAAE,IAAI,oBAAoB,GAAG;IACxF,gBAAgB,EAAE,MAAM,CAAC;IACzB,mBAAmB,EAAE,SAAS,GAAG,EAAE,CAAC;CACrC,CAOA;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAOhF"}
package/dest/utils.js CHANGED
@@ -1,5 +1,6 @@
1
1
  import { ErrorsAbi } from '@aztec/l1-artifacts/ErrorsAbi';
2
2
  import { BaseError, ContractFunctionRevertedError, decodeErrorResult, decodeEventLog } from 'viem';
3
+ import { formatAbiItem, formatAbiParams } from 'viem/utils';
3
4
  export class FormattedViemError extends Error {
4
5
  metaMessages;
5
6
  constructor(message, metaMessages){
@@ -46,6 +47,51 @@ export function prettyLogViemErrorMsg(err) {
46
47
  }
47
48
  return err?.message ?? err;
48
49
  }
50
+ export function mergeAbis(abis) {
51
+ let merged = [];
52
+ const seen = new Set();
53
+ for (const abi of abis){
54
+ for (const item of abi){
55
+ const key = getAbiItemKey(item);
56
+ if (!seen.has(key)) {
57
+ seen.add(key);
58
+ merged = [
59
+ ...merged,
60
+ item
61
+ ];
62
+ }
63
+ }
64
+ }
65
+ return merged;
66
+ }
67
+ function getAbiItemKey(item) {
68
+ if (item.type === 'function') {
69
+ const signature = formatAbiItem(item);
70
+ const outputs = formatAbiParams(item.outputs);
71
+ const stateMutability = typeof item.stateMutability === 'string' ? item.stateMutability : '';
72
+ return `function:${signature}:${outputs}:${stateMutability}`;
73
+ }
74
+ if (item.type === 'event') {
75
+ const signature = formatAbiItem(item);
76
+ const indexed = (item.inputs ?? []).map((input)=>input.indexed ? '1' : '0').join('');
77
+ const anonymous = item.anonymous ? 'anonymous' : 'not-anonymous';
78
+ return `event:${signature}:${indexed}:${anonymous}`;
79
+ }
80
+ if (item.type === 'error') {
81
+ const signature = formatAbiItem(item);
82
+ return `error:${signature}`;
83
+ }
84
+ if (item.type === 'constructor') {
85
+ const inputs = formatAbiParams(item.inputs);
86
+ const stateMutability = typeof item.stateMutability === 'string' ? item.stateMutability : '';
87
+ return `constructor::${inputs}:${stateMutability}`;
88
+ }
89
+ if (item.type === 'fallback' || item.type === 'receive') {
90
+ const stateMutability = typeof item.stateMutability === 'string' ? item.stateMutability : '';
91
+ return `${item.type}:::${stateMutability}`;
92
+ }
93
+ return 'unknown';
94
+ }
49
95
  function getNestedErrorData(error) {
50
96
  // If nothing, bail
51
97
  if (!error) {
@@ -162,3 +208,21 @@ export function tryGetCustomErrorName(err) {
162
208
  return undefined;
163
209
  }
164
210
  }
211
+ /**
212
+ * Type guard to check if a transaction is a blob transaction (EIP-4844).
213
+ * Blob transactions have maxFeePerBlobGas and blobVersionedHashes fields.
214
+ */ export function isBlobTransaction(tx) {
215
+ return 'maxFeePerBlobGas' in tx && tx.maxFeePerBlobGas !== undefined && 'blobVersionedHashes' in tx && tx.blobVersionedHashes !== undefined;
216
+ }
217
+ /**
218
+ * Calculates a percentile from an array of bigints
219
+ */ export function calculatePercentile(values, percentile) {
220
+ if (values.length === 0) {
221
+ return 0n;
222
+ }
223
+ const sorted = [
224
+ ...values
225
+ ].sort((a, b)=>a < b ? -1 : a > b ? 1 : 0);
226
+ const index = Math.ceil((sorted.length - 1) * (percentile / 100));
227
+ return sorted[index];
228
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@aztec/ethereum",
3
- "version": "3.0.3",
3
+ "version": "3.9.9-nightly.20260312",
4
4
  "type": "module",
5
5
  "exports": {
6
6
  "./account": "./dest/account.js",
@@ -17,6 +17,7 @@
17
17
  "./forwarder-proxy": "./dest/forwarder_proxy.js",
18
18
  "./l1-artifacts": "./dest/l1_artifacts.js",
19
19
  "./l1-contract-addresses": "./dest/l1_contract_addresses.js",
20
+ "./l1-fee-analysis": "./dest/l1_tx_utils/l1_fee_analyzer.js",
20
21
  "./l1-reader": "./dest/l1_reader.js",
21
22
  "./l1-tx-utils": "./dest/l1_tx_utils/index.js",
22
23
  "./l1-tx-utils-with-blobs": "./dest/l1_tx_utils/index-blobs.js",
@@ -39,7 +40,8 @@
39
40
  "build": "yarn clean && ../scripts/tsc.sh",
40
41
  "build:dev": "../scripts/tsc.sh --watch",
41
42
  "clean": "rm -rf ./dest .tsbuildinfo",
42
- "start:dev": "concurrently -k \"tsgo -b -w\" \"nodemon --watch dest --exec yarn start\"",
43
+ "generate": "./scripts/generate.sh",
44
+ "start:dev": "concurrently -k \"../scripts/tsc.sh --watch\" \"nodemon --watch dest --exec yarn start\"",
43
45
  "start": "node ./dest/index.js",
44
46
  "test": "NODE_NO_WARNINGS=1 node --experimental-vm-modules ../node_modules/.bin/jest --passWithNoTests --maxWorkers=${JEST_MAX_WORKERS:-8}",
45
47
  "proposer-address": "node ./dest/cli/forwarder_address.js"
@@ -48,10 +50,10 @@
48
50
  "../package.common.json"
49
51
  ],
50
52
  "dependencies": {
51
- "@aztec/blob-lib": "3.0.3",
52
- "@aztec/constants": "3.0.3",
53
- "@aztec/foundation": "3.0.3",
54
- "@aztec/l1-artifacts": "3.0.3",
53
+ "@aztec/blob-lib": "3.9.9-nightly.20260312",
54
+ "@aztec/constants": "3.9.9-nightly.20260312",
55
+ "@aztec/foundation": "3.9.9-nightly.20260312",
56
+ "@aztec/l1-artifacts": "3.9.9-nightly.20260312",
55
57
  "@viem/anvil": "^0.0.10",
56
58
  "dotenv": "^16.0.3",
57
59
  "lodash.chunk": "^4.2.0",
@@ -66,7 +68,7 @@
66
68
  "@types/jest": "^30.0.0",
67
69
  "@types/lodash.pickby": "^4",
68
70
  "@types/node": "^22.15.17",
69
- "@typescript/native-preview": "7.0.0-dev.20251126.1",
71
+ "@typescript/native-preview": "7.0.0-dev.20260113.1",
70
72
  "@viem/anvil": "^0.0.10",
71
73
  "get-port": "^7.1.0",
72
74
  "jest": "^30.0.0",
package/src/client.ts CHANGED
@@ -36,7 +36,7 @@ export function getPublicClient(config: Config): ViemPublicClient {
36
36
  const chain = createEthereumChain(config.l1RpcUrls, config.l1ChainId);
37
37
  return createPublicClient({
38
38
  chain: chain.chainInfo,
39
- transport: fallback(config.l1RpcUrls.map(url => http(url))),
39
+ transport: fallback(config.l1RpcUrls.map(url => http(url, { batch: false }))),
40
40
  pollingInterval: config.viemPollingIntervalMS,
41
41
  });
42
42
  }
@@ -88,7 +88,7 @@ export function createExtendedL1Client(
88
88
  const extendedClient = createWalletClient({
89
89
  account: hdAccount,
90
90
  chain,
91
- transport: fallback(rpcUrls.map(url => http(url))),
91
+ transport: fallback(rpcUrls.map(url => http(url, { batch: false }))),
92
92
  pollingInterval: pollingIntervalMS,
93
93
  }).extend(publicActions);
94
94
 
package/src/config.ts CHANGED
@@ -1,15 +1,17 @@
1
1
  import {
2
2
  type ConfigMappingsType,
3
- // type NetworkNames,
4
3
  bigintConfigHelper,
5
4
  booleanConfigHelper,
6
5
  enumConfigHelper,
7
6
  getConfigFromMappings,
7
+ getDefaultConfig,
8
8
  numberConfigHelper,
9
+ omitConfigMappings,
9
10
  optionalNumberConfigHelper,
10
11
  } from '@aztec/foundation/config';
11
12
  import { EthAddress } from '@aztec/foundation/eth-address';
12
13
 
14
+ import { l1ContractsDefaultEnv } from './generated/l1-contracts-defaults.js';
13
15
  import { type L1TxUtilsConfig, l1TxUtilsConfigMappings } from './l1_tx_utils/config.js';
14
16
 
15
17
  export type GenesisStateConfig = {
@@ -17,6 +19,8 @@ export type GenesisStateConfig = {
17
19
  testAccounts: boolean;
18
20
  /** Whether to populate the genesis state with initial fee juice for the sponsored FPC */
19
21
  sponsoredFPC: boolean;
22
+ /** Additional addresses to prefund with fee juice at genesis */
23
+ prefundAddresses: string[];
20
24
  };
21
25
 
22
26
  export type L1ContractsConfig = {
@@ -32,6 +36,8 @@ export type L1ContractsConfig = {
32
36
  lagInEpochsForValidatorSet: number;
33
37
  /** The number of epochs to lag behind the current epoch for randao selection. */
34
38
  lagInEpochsForRandao: number;
39
+ /** The number of checkpoints to lag in the inbox (prevents sequencer DOS attacks). */
40
+ inboxLag: number;
35
41
  /** The number of epochs after an epoch ends that proofs are still accepted. */
36
42
  aztecProofSubmissionEpochs: number;
37
43
  /** The deposit amount for a validator */
@@ -66,118 +72,108 @@ export type L1ContractsConfig = {
66
72
  governanceProposerQuorum?: number;
67
73
  /** Governance proposing round size */
68
74
  governanceProposerRoundSize: number;
75
+ /** Governance voting duration in seconds (only for local/devnet/next-net, default 3600) */
76
+ governanceVotingDuration?: number;
69
77
  /** The mana target for the rollup */
70
78
  manaTarget: bigint;
71
79
  /** The proving cost per mana */
72
80
  provingCostPerMana: bigint;
81
+ /** The initial ETH per fee asset price (with 1e12 precision) */
82
+ initialEthPerFeeAsset: bigint;
73
83
  /** The number of seconds to wait for an exit */
74
84
  exitDelaySeconds: number;
75
85
  } & L1TxUtilsConfig;
76
86
 
77
- export const DefaultL1ContractsConfig = {
78
- ethereumSlotDuration: 12,
79
- aztecSlotDuration: 36,
80
- aztecEpochDuration: 32,
81
- aztecTargetCommitteeSize: 48,
82
- lagInEpochsForValidatorSet: 2,
83
- lagInEpochsForRandao: 2, // For PROD, this value should be > lagInEpochsForValidatorSet
84
- aztecProofSubmissionEpochs: 1, // you have a full epoch to submit a proof after the epoch to prove ends
85
- activationThreshold: 100n * 10n ** 18n,
86
- ejectionThreshold: 50n * 10n ** 18n,
87
- localEjectionThreshold: 98n * 10n ** 18n,
88
- slashAmountSmall: 10n * 10n ** 18n,
89
- slashAmountMedium: 20n * 10n ** 18n,
90
- slashAmountLarge: 50n * 10n ** 18n,
91
- slashingRoundSizeInEpochs: 4,
92
- slashingLifetimeInRounds: 5,
93
- slashingExecutionDelayInRounds: 0, // round N may be submitted in round N + 1
94
- slashingVetoer: EthAddress.ZERO,
95
- governanceProposerRoundSize: 300,
96
- manaTarget: BigInt(100e6),
97
- provingCostPerMana: BigInt(100),
98
- exitDelaySeconds: 2 * 24 * 60 * 60,
99
- slasherFlavor: 'tally' as const,
100
- slashingOffsetInRounds: 2,
101
- slashingDisableDuration: 5 * 24 * 60 * 60, // 5 days in seconds
102
- } satisfies L1ContractsConfig;
103
-
87
+ /**
88
+ * Config mappings for L1ContractsConfig.
89
+ * Default values come from generated l1-contracts-defaults.json (source: defaults.yml).
90
+ * Real deployments use forge scripts which require explicit env vars (vm.envUint).
91
+ */
104
92
  export const l1ContractsConfigMappings: ConfigMappingsType<L1ContractsConfig> = {
105
93
  ethereumSlotDuration: {
106
94
  env: 'ETHEREUM_SLOT_DURATION',
107
95
  description: 'How many seconds an L1 slot lasts.',
108
- ...numberConfigHelper(DefaultL1ContractsConfig.ethereumSlotDuration),
96
+ ...numberConfigHelper(l1ContractsDefaultEnv.ETHEREUM_SLOT_DURATION),
109
97
  },
110
98
  aztecSlotDuration: {
111
99
  env: 'AZTEC_SLOT_DURATION',
112
100
  description: 'How many seconds an L2 slots lasts (must be multiple of ethereum slot duration).',
113
- ...numberConfigHelper(DefaultL1ContractsConfig.aztecSlotDuration),
101
+ ...numberConfigHelper(l1ContractsDefaultEnv.AZTEC_SLOT_DURATION),
114
102
  },
115
103
  aztecEpochDuration: {
116
104
  env: 'AZTEC_EPOCH_DURATION',
117
- description: `How many L2 slots an epoch lasts (maximum AZTEC_MAX_EPOCH_DURATION).`,
118
- ...numberConfigHelper(DefaultL1ContractsConfig.aztecEpochDuration),
105
+ description: `How many L2 slots an epoch lasts (maximum MAX_CHECKPOINTS_PER_EPOCH).`,
106
+ ...numberConfigHelper(l1ContractsDefaultEnv.AZTEC_EPOCH_DURATION),
119
107
  },
120
108
  aztecTargetCommitteeSize: {
121
109
  env: 'AZTEC_TARGET_COMMITTEE_SIZE',
122
110
  description: 'The target validator committee size.',
123
- ...numberConfigHelper(DefaultL1ContractsConfig.aztecTargetCommitteeSize),
111
+ ...numberConfigHelper(l1ContractsDefaultEnv.AZTEC_TARGET_COMMITTEE_SIZE),
124
112
  },
125
113
  lagInEpochsForValidatorSet: {
126
114
  env: 'AZTEC_LAG_IN_EPOCHS_FOR_VALIDATOR_SET',
127
115
  description: 'The number of epochs to lag behind the current epoch for validator selection.',
128
- ...numberConfigHelper(DefaultL1ContractsConfig.lagInEpochsForValidatorSet),
116
+ ...numberConfigHelper(l1ContractsDefaultEnv.AZTEC_LAG_IN_EPOCHS_FOR_VALIDATOR_SET),
129
117
  },
130
118
  lagInEpochsForRandao: {
131
119
  env: 'AZTEC_LAG_IN_EPOCHS_FOR_RANDAO',
132
120
  description: 'The number of epochs to lag behind the current epoch for randao selection.',
133
- ...numberConfigHelper(DefaultL1ContractsConfig.lagInEpochsForRandao),
121
+ ...numberConfigHelper(l1ContractsDefaultEnv.AZTEC_LAG_IN_EPOCHS_FOR_RANDAO),
122
+ },
123
+ inboxLag: {
124
+ env: 'AZTEC_INBOX_LAG',
125
+ description: 'The number of checkpoints to lag in the inbox (prevents sequencer DOS attacks).',
126
+ ...numberConfigHelper(l1ContractsDefaultEnv.AZTEC_INBOX_LAG),
134
127
  },
135
128
  aztecProofSubmissionEpochs: {
136
129
  env: 'AZTEC_PROOF_SUBMISSION_EPOCHS',
137
130
  description: 'The number of epochs after an epoch ends that proofs are still accepted.',
138
- ...numberConfigHelper(DefaultL1ContractsConfig.aztecProofSubmissionEpochs),
131
+ ...numberConfigHelper(l1ContractsDefaultEnv.AZTEC_PROOF_SUBMISSION_EPOCHS),
139
132
  },
140
133
  activationThreshold: {
141
134
  env: 'AZTEC_ACTIVATION_THRESHOLD',
142
135
  description: 'The deposit amount for a validator',
143
- ...bigintConfigHelper(DefaultL1ContractsConfig.activationThreshold),
136
+ ...bigintConfigHelper(BigInt(l1ContractsDefaultEnv.AZTEC_ACTIVATION_THRESHOLD)),
144
137
  },
145
138
  ejectionThreshold: {
146
139
  env: 'AZTEC_EJECTION_THRESHOLD',
147
140
  description: 'The minimum stake for a validator.',
148
- ...bigintConfigHelper(DefaultL1ContractsConfig.ejectionThreshold),
141
+ ...bigintConfigHelper(BigInt(l1ContractsDefaultEnv.AZTEC_EJECTION_THRESHOLD)),
149
142
  },
150
143
  localEjectionThreshold: {
151
144
  env: 'AZTEC_LOCAL_EJECTION_THRESHOLD',
152
145
  description:
153
146
  'The local ejection threshold for a validator. Stricter than ejectionThreshold but local to a specific rollup',
154
- ...bigintConfigHelper(DefaultL1ContractsConfig.localEjectionThreshold),
147
+ ...bigintConfigHelper(BigInt(l1ContractsDefaultEnv.AZTEC_LOCAL_EJECTION_THRESHOLD)),
155
148
  },
156
149
  slashingOffsetInRounds: {
157
150
  env: 'AZTEC_SLASHING_OFFSET_IN_ROUNDS',
158
151
  description:
159
152
  'How many slashing rounds back we slash (ie when slashing in round N, we slash for offenses committed during epochs of round N-offset)',
160
- ...numberConfigHelper(DefaultL1ContractsConfig.slashingOffsetInRounds),
153
+ ...numberConfigHelper(l1ContractsDefaultEnv.AZTEC_SLASHING_OFFSET_IN_ROUNDS),
161
154
  },
162
155
  slasherFlavor: {
163
156
  env: 'AZTEC_SLASHER_FLAVOR',
164
157
  description: 'Type of slasher proposer (empire, tally, or none)',
165
- ...enumConfigHelper(['empire', 'tally', 'none'] as const, DefaultL1ContractsConfig.slasherFlavor),
158
+ ...enumConfigHelper(
159
+ ['empire', 'tally', 'none'] as const,
160
+ l1ContractsDefaultEnv.AZTEC_SLASHER_FLAVOR as 'empire' | 'tally' | 'none',
161
+ ),
166
162
  },
167
163
  slashAmountSmall: {
168
164
  env: 'AZTEC_SLASH_AMOUNT_SMALL',
169
165
  description: 'Small slashing amount for light offenses',
170
- ...bigintConfigHelper(DefaultL1ContractsConfig.slashAmountSmall),
166
+ ...bigintConfigHelper(BigInt(l1ContractsDefaultEnv.AZTEC_SLASH_AMOUNT_SMALL)),
171
167
  },
172
168
  slashAmountMedium: {
173
169
  env: 'AZTEC_SLASH_AMOUNT_MEDIUM',
174
170
  description: 'Medium slashing amount for moderate offenses',
175
- ...bigintConfigHelper(DefaultL1ContractsConfig.slashAmountMedium),
171
+ ...bigintConfigHelper(BigInt(l1ContractsDefaultEnv.AZTEC_SLASH_AMOUNT_MEDIUM)),
176
172
  },
177
173
  slashAmountLarge: {
178
174
  env: 'AZTEC_SLASH_AMOUNT_LARGE',
179
175
  description: 'Large slashing amount for severe offenses',
180
- ...bigintConfigHelper(DefaultL1ContractsConfig.slashAmountLarge),
176
+ ...bigintConfigHelper(BigInt(l1ContractsDefaultEnv.AZTEC_SLASH_AMOUNT_LARGE)),
181
177
  },
182
178
  slashingQuorum: {
183
179
  env: 'AZTEC_SLASHING_QUORUM',
@@ -187,28 +183,28 @@ export const l1ContractsConfigMappings: ConfigMappingsType<L1ContractsConfig> =
187
183
  slashingRoundSizeInEpochs: {
188
184
  env: 'AZTEC_SLASHING_ROUND_SIZE_IN_EPOCHS',
189
185
  description: 'The slashing round size',
190
- ...numberConfigHelper(DefaultL1ContractsConfig.slashingRoundSizeInEpochs),
186
+ ...numberConfigHelper(l1ContractsDefaultEnv.AZTEC_SLASHING_ROUND_SIZE_IN_EPOCHS),
191
187
  },
192
188
  slashingLifetimeInRounds: {
193
189
  env: 'AZTEC_SLASHING_LIFETIME_IN_ROUNDS',
194
190
  description: 'The slashing lifetime in rounds',
195
- ...numberConfigHelper(DefaultL1ContractsConfig.slashingLifetimeInRounds),
191
+ ...numberConfigHelper(l1ContractsDefaultEnv.AZTEC_SLASHING_LIFETIME_IN_ROUNDS),
196
192
  },
197
193
  slashingExecutionDelayInRounds: {
198
194
  env: 'AZTEC_SLASHING_EXECUTION_DELAY_IN_ROUNDS',
199
195
  description: 'The slashing execution delay in rounds',
200
- ...numberConfigHelper(DefaultL1ContractsConfig.slashingExecutionDelayInRounds),
196
+ ...numberConfigHelper(l1ContractsDefaultEnv.AZTEC_SLASHING_EXECUTION_DELAY_IN_ROUNDS),
201
197
  },
202
198
  slashingVetoer: {
203
199
  env: 'AZTEC_SLASHING_VETOER',
204
200
  description: 'The slashing vetoer',
205
201
  parseEnv: (val: string) => EthAddress.fromString(val),
206
- defaultValue: DefaultL1ContractsConfig.slashingVetoer,
202
+ defaultValue: EthAddress.fromString(l1ContractsDefaultEnv.AZTEC_SLASHING_VETOER),
207
203
  },
208
204
  slashingDisableDuration: {
209
205
  env: 'AZTEC_SLASHING_DISABLE_DURATION',
210
206
  description: 'How long slashing can be disabled for in seconds when vetoer disables it',
211
- ...numberConfigHelper(DefaultL1ContractsConfig.slashingDisableDuration),
207
+ ...numberConfigHelper(l1ContractsDefaultEnv.AZTEC_SLASHING_DISABLE_DURATION),
212
208
  },
213
209
  governanceProposerQuorum: {
214
210
  env: 'AZTEC_GOVERNANCE_PROPOSER_QUORUM',
@@ -218,26 +214,42 @@ export const l1ContractsConfigMappings: ConfigMappingsType<L1ContractsConfig> =
218
214
  governanceProposerRoundSize: {
219
215
  env: 'AZTEC_GOVERNANCE_PROPOSER_ROUND_SIZE',
220
216
  description: 'The governance proposing round size',
221
- ...numberConfigHelper(DefaultL1ContractsConfig.governanceProposerRoundSize),
217
+ ...numberConfigHelper(l1ContractsDefaultEnv.AZTEC_GOVERNANCE_PROPOSER_ROUND_SIZE),
218
+ },
219
+ governanceVotingDuration: {
220
+ env: 'AZTEC_GOVERNANCE_VOTING_DURATION',
221
+ description: 'Governance voting duration in seconds (only for local/devnet/next-net)',
222
+ ...numberConfigHelper(3600), // 1 hour default, not in generated defaults as it's deployment-time only
222
223
  },
223
224
  manaTarget: {
224
225
  env: 'AZTEC_MANA_TARGET',
225
226
  description: 'The mana target for the rollup',
226
- ...bigintConfigHelper(DefaultL1ContractsConfig.manaTarget),
227
+ ...bigintConfigHelper(BigInt(l1ContractsDefaultEnv.AZTEC_MANA_TARGET)),
227
228
  },
228
229
  provingCostPerMana: {
229
230
  env: 'AZTEC_PROVING_COST_PER_MANA',
230
231
  description: 'The proving cost per mana',
231
- ...bigintConfigHelper(DefaultL1ContractsConfig.provingCostPerMana),
232
+ ...bigintConfigHelper(BigInt(l1ContractsDefaultEnv.AZTEC_PROVING_COST_PER_MANA)),
233
+ },
234
+ initialEthPerFeeAsset: {
235
+ env: 'AZTEC_INITIAL_ETH_PER_FEE_ASSET',
236
+ description: 'The initial ETH per fee asset price (with 1e12 precision)',
237
+ ...bigintConfigHelper(BigInt(l1ContractsDefaultEnv.AZTEC_INITIAL_ETH_PER_FEE_ASSET)),
232
238
  },
233
239
  exitDelaySeconds: {
234
240
  env: 'AZTEC_EXIT_DELAY_SECONDS',
235
241
  description: 'The delay before a validator can exit the set',
236
- ...numberConfigHelper(DefaultL1ContractsConfig.exitDelaySeconds),
242
+ ...numberConfigHelper(l1ContractsDefaultEnv.AZTEC_EXIT_DELAY_SECONDS),
237
243
  },
238
- ...l1TxUtilsConfigMappings,
244
+ ...omitConfigMappings(l1TxUtilsConfigMappings, ['ethereumSlotDuration']),
239
245
  };
240
246
 
247
+ /**
248
+ * Default L1 contracts configuration derived from l1ContractsConfigMappings.
249
+ * Source of truth: spartan/environments/defaults.yml -> defaults.l1-contracts
250
+ */
251
+ export const DefaultL1ContractsConfig = getDefaultConfig(l1ContractsConfigMappings);
252
+
241
253
  export const genesisStateConfigMappings: ConfigMappingsType<GenesisStateConfig> = {
242
254
  testAccounts: {
243
255
  env: 'TEST_ACCOUNTS',
@@ -249,6 +261,16 @@ export const genesisStateConfigMappings: ConfigMappingsType<GenesisStateConfig>
249
261
  description: 'Whether to populate the genesis state with initial fee juice for the sponsored FPC.',
250
262
  ...booleanConfigHelper(false),
251
263
  },
264
+ prefundAddresses: {
265
+ env: 'PREFUND_ADDRESSES',
266
+ description: 'Comma-separated list of Aztec addresses to prefund with fee juice at genesis.',
267
+ parseEnv: (val: string) =>
268
+ val
269
+ .split(',')
270
+ .map(a => a.trim())
271
+ .filter(a => a.length > 0),
272
+ defaultValue: [],
273
+ },
252
274
  };
253
275
 
254
276
  export function getL1ContractsConfigEnvVars(): L1ContractsConfig {
@@ -0,0 +1,157 @@
1
+ # L1 Contract Wrappers
2
+
3
+ This folder contains TypeScript wrappers for L1 contracts defined in `l1-contracts/`. These wrappers are used by the node client to interact with the rollup and related contracts on Ethereum.
4
+
5
+ ## Purpose
6
+
7
+ The goal of wrapping is to shield consumers from L1-specific and viem-specific details. Clients using these wrappers interact with domain types and branded types native to the Aztec codebase, without needing to understand viem's ABI type system or deal with raw types like `Hex` and `bigint`.
8
+
9
+ ## Type Safety
10
+
11
+ ### Explicit Return Types
12
+
13
+ Every function in the contract wrappers must declare its return type explicitly. This is critical because viem's type inference over ABI types is slow and significantly impacts IDE performance.
14
+
15
+ ```typescript
16
+ // Good: Explicit return type
17
+ async getSlotNumber(): Promise<SlotNumber> {
18
+ return SlotNumber.fromBigInt(await this.rollup.read.getCurrentSlot());
19
+ }
20
+
21
+ // Bad: Inferred return type (slow)
22
+ async getSlotNumber() {
23
+ return SlotNumber.fromBigInt(await this.rollup.read.getCurrentSlot());
24
+ }
25
+ ```
26
+
27
+ ### Branded and Domain Types
28
+
29
+ Use branded types and domain-specific types instead of viem's autogenerated types for both arguments and return values:
30
+
31
+ - `CheckpointNumber`, `EpochNumber`, `SlotNumber` instead of `bigint`
32
+ - `EthAddress` instead of `` `0x${string}` `` or `Hex`
33
+ - `Fr`, `Buffer32` instead of `Hex` for hashes and field elements
34
+ - Custom domain types (e.g., `CheckpointLog`, `AttesterView`) instead of raw tuples
35
+
36
+ Type conversions happen inside wrapper methods, not at the call site:
37
+
38
+ ```typescript
39
+ async getCheckpoint(checkpointNumber: CheckpointNumber): Promise<CheckpointLog> {
40
+ const result = await this.rollup.read.getCheckpoint([BigInt(checkpointNumber)]);
41
+ return {
42
+ archive: Fr.fromString(result.archive),
43
+ headerHash: Buffer32.fromString(result.headerHash),
44
+ blockCount: result.blockCount,
45
+ };
46
+ }
47
+ ```
48
+
49
+ ## Wrapper Pattern
50
+
51
+ ### Basic Structure
52
+
53
+ Each wrapper follows a consistent structure:
54
+
55
+ ```typescript
56
+ export class FooContract {
57
+ private readonly foo: GetContractReturnType<typeof FooAbi, ViemClient>;
58
+
59
+ constructor(
60
+ public readonly client: ViemClient,
61
+ address: Hex | EthAddress,
62
+ ) {
63
+ if (address instanceof EthAddress) {
64
+ address = address.toString();
65
+ }
66
+ this.foo = getContract({ address, abi: FooAbi, client });
67
+ }
68
+
69
+ public get address(): Hex {
70
+ return this.foo.address;
71
+ }
72
+
73
+ public getContract(): GetContractReturnType<typeof FooAbi, ViemClient> {
74
+ return this.foo;
75
+ }
76
+ }
77
+ ```
78
+
79
+ The raw contract is exposed via `getContract()` for cases where direct access is needed, but most consumers should use the typed wrapper methods. Relying on `getContract()` is a code smell and should be avoided.
80
+
81
+ ### Static Factory Methods
82
+
83
+ Wrappers may provide static factory methods for common initialization patterns:
84
+
85
+ - `getFromConfig(config)` - construct from configuration object
86
+ - `getFromL1ContractsValues(deployResult)` - construct from deployment result
87
+
88
+ ### Wallet Assertions
89
+
90
+ For write operations that require a wallet, use an assertion helper:
91
+
92
+ ```typescript
93
+ private assertWallet(): GetContractReturnType<typeof FooAbi, ExtendedViemWalletClient> {
94
+ if (!isExtendedClient(this.client)) {
95
+ throw new Error('Wallet client is required for this operation');
96
+ }
97
+ return this.foo as GetContractReturnType<typeof FooAbi, ExtendedViemWalletClient>;
98
+ }
99
+ ```
100
+
101
+ ## Event Handling
102
+
103
+ ### Event Log Types
104
+
105
+ Event logs are wrapped in `L1EventLog<T>` to include L1 block context:
106
+
107
+ ```typescript
108
+ type L1EventLog<T> = {
109
+ l1BlockNumber: bigint;
110
+ l1BlockHash: Buffer32;
111
+ l1TransactionHash: Hex;
112
+ args: T;
113
+ };
114
+ ```
115
+
116
+ ### Event Fetching
117
+
118
+ Methods that fetch events convert viem's raw logs to domain types:
119
+
120
+ ```typescript
121
+ async getCheckpointProposedEvents(fromBlock: bigint, toBlock: bigint): Promise<CheckpointProposedLog[]> {
122
+ const logs = await this.rollup.getEvents.CheckpointProposed({}, { fromBlock, toBlock });
123
+ return logs.map(log => ({
124
+ l1BlockNumber: log.blockNumber!,
125
+ l1BlockHash: Buffer32.fromString(log.blockHash!),
126
+ l1TransactionHash: log.transactionHash!,
127
+ args: {
128
+ checkpointNumber: CheckpointNumber.fromBigInt(log.args.checkpointNumber!),
129
+ // ... convert other fields
130
+ },
131
+ }));
132
+ }
133
+ ```
134
+
135
+ ### Event Listeners
136
+
137
+ For reactive event handling, wrapper methods convert arguments before invoking callbacks:
138
+
139
+ ```typescript
140
+ public listenToCheckpointInvalidated(
141
+ callback: (args: { checkpointNumber: CheckpointNumber }) => unknown,
142
+ ): WatchContractEventReturnType {
143
+ return this.rollup.watchEvent.CheckpointInvalidated({}, {
144
+ onLogs: logs => {
145
+ for (const log of logs) {
146
+ if (log.args.checkpointNumber !== undefined) {
147
+ callback({ checkpointNumber: CheckpointNumber.fromBigInt(log.args.checkpointNumber) });
148
+ }
149
+ }
150
+ },
151
+ });
152
+ }
153
+ ```
154
+
155
+ ## Error Handling
156
+
157
+ Custom error classes in `errors.ts` extend `Error` and set `this.name` for proper error identification. Include relevant context as public readonly properties.
@@ -12,7 +12,7 @@ export interface IEmpireBase {
12
12
  getRoundInfo(
13
13
  rollupAddress: Hex,
14
14
  round: bigint,
15
- ): Promise<{ lastSignalSlot: SlotNumber; payloadWithMostSignals: Hex; executed: boolean }>;
15
+ ): Promise<{ lastSignalSlot: SlotNumber; payloadWithMostSignals: Hex; quorumReached: boolean; executed: boolean }>;
16
16
  computeRound(slot: SlotNumber): Promise<bigint>;
17
17
  createSignalRequest(payload: Hex): L1TxRequest;
18
18
  createSignalRequestWithSignature(
@@ -22,6 +22,8 @@ export interface IEmpireBase {
22
22
  signerAddress: Hex,
23
23
  signer: (msg: TypedDataDefinition) => Promise<Hex>,
24
24
  ): Promise<L1TxRequest>;
25
+ /** Checks if a payload was ever submitted to governance via submitRoundWinner. */
26
+ hasPayloadBeenProposed(payload: Hex, fromBlock: bigint): Promise<boolean>;
25
27
  }
26
28
 
27
29
  export function encodeSignal(payload: Hex): Hex {