@fhevm/sdk 0.14.4 → 0.14.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 (286) hide show
  1. package/_cjs/core/_version.js +1 -1
  2. package/_cjs/core/actions/chain/fetchFheEncryptionKeyBytes.js +2 -1
  3. package/_cjs/core/actions/chain/fetchFheEncryptionKeyBytes.js.map +1 -1
  4. package/_cjs/core/chains/definitions/bscTestnet.js +36 -0
  5. package/_cjs/core/chains/definitions/bscTestnet.js.map +1 -0
  6. package/_cjs/core/chains/definitions/mainnet.js +3 -0
  7. package/_cjs/core/chains/definitions/mainnet.js.map +1 -1
  8. package/_cjs/core/chains/definitions/sepolia.js +3 -0
  9. package/_cjs/core/chains/definitions/sepolia.js.map +1 -1
  10. package/_cjs/core/chains/index.js +3 -1
  11. package/_cjs/core/chains/index.js.map +1 -1
  12. package/_cjs/core/clients/decorators/base.js.map +1 -1
  13. package/_cjs/core/clients/decorators/encrypt.js +4 -0
  14. package/_cjs/core/clients/decorators/encrypt.js.map +1 -1
  15. package/_cjs/core/coprocessor/ZkProofBuilder-p.js.map +1 -1
  16. package/_cjs/core/coprocessor/encrypt.js +5 -1
  17. package/_cjs/core/coprocessor/encrypt.js.map +1 -1
  18. package/_cjs/core/errors/FheEncryptionKeyVerificationError.js +14 -0
  19. package/_cjs/core/errors/FheEncryptionKeyVerificationError.js.map +1 -0
  20. package/_cjs/core/errors/FhevmErrorBase.js +0 -1
  21. package/_cjs/core/errors/FhevmErrorBase.js.map +1 -1
  22. package/_cjs/core/errors/RelayerErrorBase.js +0 -1
  23. package/_cjs/core/errors/RelayerErrorBase.js.map +1 -1
  24. package/_cjs/core/host-contracts/HostContractVersion-p.js +2 -0
  25. package/_cjs/core/host-contracts/HostContractVersion-p.js.map +1 -1
  26. package/_cjs/core/host-contracts/abi-fragments/fragments.js +50 -1
  27. package/_cjs/core/host-contracts/abi-fragments/fragments.js.map +1 -1
  28. package/_cjs/core/key/FheEncryptionKeyCache-p.js +50 -56
  29. package/_cjs/core/key/FheEncryptionKeyCache-p.js.map +1 -1
  30. package/_cjs/core/key/copyFheEncryptionKeyBytes-p.js +17 -0
  31. package/_cjs/core/key/copyFheEncryptionKeyBytes-p.js.map +1 -0
  32. package/_cjs/core/key/ensureFheEncryptionKeyDownload.js +134 -0
  33. package/_cjs/core/key/ensureFheEncryptionKeyDownload.js.map +1 -0
  34. package/_cjs/core/key/fetchFheEncryptionKey.js +4 -24
  35. package/_cjs/core/key/fetchFheEncryptionKey.js.map +1 -1
  36. package/_cjs/core/key/fetchFheEncryptionKeyBytes.js +2 -32
  37. package/_cjs/core/key/fetchFheEncryptionKeyBytes.js.map +1 -1
  38. package/_cjs/core/key/verifyFheEncryptionKeyBytes-p.js +245 -0
  39. package/_cjs/core/key/verifyFheEncryptionKeyBytes-p.js.map +1 -0
  40. package/_cjs/core/modules/encrypt/mock.js +7 -90
  41. package/_cjs/core/modules/encrypt/mock.js.map +1 -1
  42. package/_cjs/core/modules/encrypt/module/api-p.js +0 -65
  43. package/_cjs/core/modules/encrypt/module/api-p.js.map +1 -1
  44. package/_cjs/core/modules/encrypt/module/index.js +0 -3
  45. package/_cjs/core/modules/encrypt/module/index.js.map +1 -1
  46. package/_cjs/core/modules/relayer/cleartext/mock.js +1 -0
  47. package/_cjs/core/modules/relayer/cleartext/mock.js.map +1 -1
  48. package/_cjs/core/modules/relayer/module/RelayerAsyncRequest.js +12 -2
  49. package/_cjs/core/modules/relayer/module/RelayerAsyncRequest.js.map +1 -1
  50. package/_cjs/core/modules/relayer/module/fetchFheEncryptionKeySource.js +5 -3
  51. package/_cjs/core/modules/relayer/module/fetchFheEncryptionKeySource.js.map +1 -1
  52. package/_cjs/core/modules/relayer/module/relayerUrl.js +37 -0
  53. package/_cjs/core/modules/relayer/module/relayerUrl.js.map +1 -1
  54. package/_cjs/core/runtime/CoreFhevm-p.js +88 -11
  55. package/_cjs/core/runtime/CoreFhevm-p.js.map +1 -1
  56. package/_cjs/core/types/index.js.map +1 -1
  57. package/_cjs/ethers/clients/createFhevmDecryptClient.js +4 -1
  58. package/_cjs/ethers/clients/createFhevmDecryptClient.js.map +1 -1
  59. package/_cjs/viem/clients/createFhevmDecryptClient.js +4 -1
  60. package/_cjs/viem/clients/createFhevmDecryptClient.js.map +1 -1
  61. package/_cjs/wasm/tfhe/loadTfheLib.js.map +1 -1
  62. package/_cjs/wasm/tkms/loadKmsLib.js.map +1 -1
  63. package/_esm/core/_version.js +1 -1
  64. package/_esm/core/actions/chain/fetchFheEncryptionKeyBytes.js +7 -1
  65. package/_esm/core/actions/chain/fetchFheEncryptionKeyBytes.js.map +1 -1
  66. package/_esm/core/chains/definitions/bscTestnet.js +33 -0
  67. package/_esm/core/chains/definitions/bscTestnet.js.map +1 -0
  68. package/_esm/core/chains/definitions/mainnet.js +3 -0
  69. package/_esm/core/chains/definitions/mainnet.js.map +1 -1
  70. package/_esm/core/chains/definitions/sepolia.js +3 -0
  71. package/_esm/core/chains/definitions/sepolia.js.map +1 -1
  72. package/_esm/core/chains/index.js +1 -0
  73. package/_esm/core/chains/index.js.map +1 -1
  74. package/_esm/core/clients/decorators/base.js.map +1 -1
  75. package/_esm/core/clients/decorators/encrypt-p.js +1 -1
  76. package/_esm/core/clients/decorators/encrypt-p.js.map +1 -1
  77. package/_esm/core/clients/decorators/encrypt.js +6 -0
  78. package/_esm/core/clients/decorators/encrypt.js.map +1 -1
  79. package/_esm/core/coprocessor/ZkProofBuilder-p.js +1 -1
  80. package/_esm/core/coprocessor/ZkProofBuilder-p.js.map +1 -1
  81. package/_esm/core/coprocessor/encrypt.js +5 -1
  82. package/_esm/core/coprocessor/encrypt.js.map +1 -1
  83. package/_esm/core/errors/FheEncryptionKeyVerificationError.js +15 -0
  84. package/_esm/core/errors/FheEncryptionKeyVerificationError.js.map +1 -0
  85. package/_esm/core/errors/FhevmErrorBase.js +0 -1
  86. package/_esm/core/errors/FhevmErrorBase.js.map +1 -1
  87. package/_esm/core/errors/RelayerErrorBase.js +0 -1
  88. package/_esm/core/errors/RelayerErrorBase.js.map +1 -1
  89. package/_esm/core/host-contracts/HostContractVersion-p.js +2 -1
  90. package/_esm/core/host-contracts/HostContractVersion-p.js.map +1 -1
  91. package/_esm/core/host-contracts/abi-fragments/fragments.js +61 -0
  92. package/_esm/core/host-contracts/abi-fragments/fragments.js.map +1 -1
  93. package/_esm/core/key/FheEncryptionKeyCache-p.js +91 -75
  94. package/_esm/core/key/FheEncryptionKeyCache-p.js.map +1 -1
  95. package/_esm/core/key/copyFheEncryptionKeyBytes-p.js +21 -0
  96. package/_esm/core/key/copyFheEncryptionKeyBytes-p.js.map +1 -0
  97. package/_esm/core/key/ensureFheEncryptionKeyDownload.js +213 -0
  98. package/_esm/core/key/ensureFheEncryptionKeyDownload.js.map +1 -0
  99. package/_esm/core/key/fetchFheEncryptionKey.js +6 -26
  100. package/_esm/core/key/fetchFheEncryptionKey.js.map +1 -1
  101. package/_esm/core/key/fetchFheEncryptionKeyBytes.js +4 -41
  102. package/_esm/core/key/fetchFheEncryptionKeyBytes.js.map +1 -1
  103. package/_esm/core/key/verifyFheEncryptionKeyBytes-p.js +345 -0
  104. package/_esm/core/key/verifyFheEncryptionKeyBytes-p.js.map +1 -0
  105. package/_esm/core/modules/encrypt/mock.js +7 -96
  106. package/_esm/core/modules/encrypt/mock.js.map +1 -1
  107. package/_esm/core/modules/encrypt/module/api-p.js +0 -71
  108. package/_esm/core/modules/encrypt/module/api-p.js.map +1 -1
  109. package/_esm/core/modules/encrypt/module/index.js +1 -4
  110. package/_esm/core/modules/encrypt/module/index.js.map +1 -1
  111. package/_esm/core/modules/relayer/cleartext/mock.js +1 -0
  112. package/_esm/core/modules/relayer/cleartext/mock.js.map +1 -1
  113. package/_esm/core/modules/relayer/module/RelayerAsyncRequest.js +14 -2
  114. package/_esm/core/modules/relayer/module/RelayerAsyncRequest.js.map +1 -1
  115. package/_esm/core/modules/relayer/module/fetchFheEncryptionKeySource.js +7 -4
  116. package/_esm/core/modules/relayer/module/fetchFheEncryptionKeySource.js.map +1 -1
  117. package/_esm/core/modules/relayer/module/relayerUrl.js +48 -1
  118. package/_esm/core/modules/relayer/module/relayerUrl.js.map +1 -1
  119. package/_esm/core/runtime/CoreFhevm-p.js +128 -15
  120. package/_esm/core/runtime/CoreFhevm-p.js.map +1 -1
  121. package/_esm/core/types/index.js.map +1 -1
  122. package/_esm/ethers/clients/createFhevmDecryptClient.js +5 -1
  123. package/_esm/ethers/clients/createFhevmDecryptClient.js.map +1 -1
  124. package/_esm/viem/clients/createFhevmDecryptClient.js +5 -1
  125. package/_esm/viem/clients/createFhevmDecryptClient.js.map +1 -1
  126. package/_types/core/actions/chain/fetchFheEncryptionKeyBytes.d.ts +5 -0
  127. package/_types/core/actions/chain/fetchFheEncryptionKeyBytes.d.ts.map +1 -1
  128. package/_types/core/chains/definitions/bscTestnet.d.ts +3 -0
  129. package/_types/core/chains/definitions/bscTestnet.d.ts.map +1 -0
  130. package/_types/core/chains/definitions/mainnet.d.ts +3 -0
  131. package/_types/core/chains/definitions/mainnet.d.ts.map +1 -1
  132. package/_types/core/chains/definitions/sepolia.d.ts.map +1 -1
  133. package/_types/core/chains/index.d.ts +1 -0
  134. package/_types/core/chains/index.d.ts.map +1 -1
  135. package/_types/core/clients/decorators/base.d.ts +4 -1
  136. package/_types/core/clients/decorators/base.d.ts.map +1 -1
  137. package/_types/core/clients/decorators/encrypt.d.ts.map +1 -1
  138. package/_types/core/coprocessor/ZkProofBuilder-p.d.ts +2 -4
  139. package/_types/core/coprocessor/ZkProofBuilder-p.d.ts.map +1 -1
  140. package/_types/core/coprocessor/encrypt.d.ts +2 -8
  141. package/_types/core/coprocessor/encrypt.d.ts.map +1 -1
  142. package/_types/core/errors/FheEncryptionKeyVerificationError.d.ts +16 -0
  143. package/_types/core/errors/FheEncryptionKeyVerificationError.d.ts.map +1 -0
  144. package/_types/core/errors/FhevmErrorBase.d.ts.map +1 -1
  145. package/_types/core/errors/RelayerErrorBase.d.ts.map +1 -1
  146. package/_types/core/errors/TfheError.d.ts +1 -1
  147. package/_types/core/host-contracts/HostContractVersion-p.d.ts +4 -0
  148. package/_types/core/host-contracts/HostContractVersion-p.d.ts.map +1 -1
  149. package/_types/core/host-contracts/abi-fragments/fragments.d.ts +12 -0
  150. package/_types/core/host-contracts/abi-fragments/fragments.d.ts.map +1 -1
  151. package/_types/core/key/FheEncryptionKeyCache-p.d.ts +45 -21
  152. package/_types/core/key/FheEncryptionKeyCache-p.d.ts.map +1 -1
  153. package/_types/core/key/copyFheEncryptionKeyBytes-p.d.ts +9 -0
  154. package/_types/core/key/copyFheEncryptionKeyBytes-p.d.ts.map +1 -0
  155. package/_types/core/key/ensureFheEncryptionKeyDownload.d.ts +73 -0
  156. package/_types/core/key/ensureFheEncryptionKeyDownload.d.ts.map +1 -0
  157. package/_types/core/key/fetchFheEncryptionKey.d.ts +2 -4
  158. package/_types/core/key/fetchFheEncryptionKey.d.ts.map +1 -1
  159. package/_types/core/key/fetchFheEncryptionKeyBytes.d.ts +2 -4
  160. package/_types/core/key/fetchFheEncryptionKeyBytes.d.ts.map +1 -1
  161. package/_types/core/key/verifyFheEncryptionKeyBytes-p.d.ts +61 -0
  162. package/_types/core/key/verifyFheEncryptionKeyBytes-p.d.ts.map +1 -0
  163. package/_types/core/modules/encrypt/mock.d.ts +1 -4
  164. package/_types/core/modules/encrypt/mock.d.ts.map +1 -1
  165. package/_types/core/modules/encrypt/module/api-p.d.ts +1 -4
  166. package/_types/core/modules/encrypt/module/api-p.d.ts.map +1 -1
  167. package/_types/core/modules/encrypt/module/index.d.ts.map +1 -1
  168. package/_types/core/modules/encrypt/types.d.ts +2 -26
  169. package/_types/core/modules/encrypt/types.d.ts.map +1 -1
  170. package/_types/core/modules/relayer/cleartext/mock.d.ts.map +1 -1
  171. package/_types/core/modules/relayer/module/RelayerAsyncRequest.d.ts +1 -0
  172. package/_types/core/modules/relayer/module/RelayerAsyncRequest.d.ts.map +1 -1
  173. package/_types/core/modules/relayer/module/fetchFheEncryptionKeySource.d.ts.map +1 -1
  174. package/_types/core/modules/relayer/module/relayerUrl.d.ts +12 -1
  175. package/_types/core/modules/relayer/module/relayerUrl.d.ts.map +1 -1
  176. package/_types/core/modules/relayer/types.d.ts +9 -1
  177. package/_types/core/modules/relayer/types.d.ts.map +1 -1
  178. package/_types/core/runtime/CoreFhevm-p.d.ts +23 -1
  179. package/_types/core/runtime/CoreFhevm-p.d.ts.map +1 -1
  180. package/_types/core/types/coreFhevmClient.d.ts +31 -4
  181. package/_types/core/types/coreFhevmClient.d.ts.map +1 -1
  182. package/_types/core/types/fhevmChain.d.ts +7 -0
  183. package/_types/core/types/fhevmChain.d.ts.map +1 -1
  184. package/_types/core/types/hostContract.d.ts +1 -0
  185. package/_types/core/types/hostContract.d.ts.map +1 -1
  186. package/_types/core/types/index.d.ts +1 -0
  187. package/_types/core/types/index.d.ts.map +1 -1
  188. package/_types/core/types/relayer.d.ts +6 -0
  189. package/_types/core/types/relayer.d.ts.map +1 -1
  190. package/_types/core/types/zkProofBuilder-p.d.ts +2 -4
  191. package/_types/core/types/zkProofBuilder-p.d.ts.map +1 -1
  192. package/_types/ethers/cleartext/createFhevmCleartextBaseClient.d.ts +1 -1
  193. package/_types/ethers/cleartext/createFhevmCleartextBaseClient.d.ts.map +1 -1
  194. package/_types/ethers/cleartext/createFhevmCleartextClient.d.ts +1 -1
  195. package/_types/ethers/cleartext/createFhevmCleartextClient.d.ts.map +1 -1
  196. package/_types/ethers/cleartext/createFhevmCleartextDecryptClient.d.ts +1 -1
  197. package/_types/ethers/cleartext/createFhevmCleartextDecryptClient.d.ts.map +1 -1
  198. package/_types/ethers/cleartext/createFhevmCleartextEncryptClient.d.ts +1 -1
  199. package/_types/ethers/cleartext/createFhevmCleartextEncryptClient.d.ts.map +1 -1
  200. package/_types/ethers/clients/createFhevmBaseClient.d.ts +1 -1
  201. package/_types/ethers/clients/createFhevmBaseClient.d.ts.map +1 -1
  202. package/_types/ethers/clients/createFhevmClient.d.ts +2 -2
  203. package/_types/ethers/clients/createFhevmClient.d.ts.map +1 -1
  204. package/_types/ethers/clients/createFhevmDecryptClient.d.ts +2 -2
  205. package/_types/ethers/clients/createFhevmDecryptClient.d.ts.map +1 -1
  206. package/_types/ethers/clients/createFhevmEncryptClient.d.ts +2 -2
  207. package/_types/ethers/clients/createFhevmEncryptClient.d.ts.map +1 -1
  208. package/_types/viem/cleartext/createFhevmCleartextBaseClient.d.ts +1 -1
  209. package/_types/viem/cleartext/createFhevmCleartextBaseClient.d.ts.map +1 -1
  210. package/_types/viem/cleartext/createFhevmCleartextClient.d.ts +1 -1
  211. package/_types/viem/cleartext/createFhevmCleartextClient.d.ts.map +1 -1
  212. package/_types/viem/cleartext/createFhevmCleartextDecryptClient.d.ts +1 -1
  213. package/_types/viem/cleartext/createFhevmCleartextDecryptClient.d.ts.map +1 -1
  214. package/_types/viem/cleartext/createFhevmCleartextEncryptClient.d.ts +1 -1
  215. package/_types/viem/cleartext/createFhevmCleartextEncryptClient.d.ts.map +1 -1
  216. package/_types/viem/clients/createFhevmBaseClient.d.ts +1 -1
  217. package/_types/viem/clients/createFhevmBaseClient.d.ts.map +1 -1
  218. package/_types/viem/clients/createFhevmClient.d.ts +2 -2
  219. package/_types/viem/clients/createFhevmClient.d.ts.map +1 -1
  220. package/_types/viem/clients/createFhevmDecryptClient.d.ts +2 -2
  221. package/_types/viem/clients/createFhevmDecryptClient.d.ts.map +1 -1
  222. package/_types/viem/clients/createFhevmEncryptClient.d.ts +2 -2
  223. package/_types/viem/clients/createFhevmEncryptClient.d.ts.map +1 -1
  224. package/core/_version.ts +1 -1
  225. package/core/actions/chain/fetchFheEncryptionKeyBytes.ts +7 -1
  226. package/core/chains/definitions/bscTestnet.ts +34 -0
  227. package/core/chains/definitions/mainnet.ts +3 -0
  228. package/core/chains/definitions/sepolia.ts +3 -0
  229. package/core/chains/index.ts +1 -0
  230. package/core/clients/decorators/base.ts +4 -1
  231. package/core/clients/decorators/encrypt-p.ts +1 -1
  232. package/core/clients/decorators/encrypt.ts +6 -0
  233. package/core/coprocessor/ZkProofBuilder-p.ts +3 -5
  234. package/core/coprocessor/encrypt.ts +10 -10
  235. package/core/errors/FheEncryptionKeyVerificationError.ts +27 -0
  236. package/core/errors/FhevmErrorBase.ts +0 -1
  237. package/core/errors/RelayerErrorBase.ts +0 -1
  238. package/core/errors/TfheError.ts +1 -1
  239. package/core/host-contracts/HostContractVersion-p.ts +2 -1
  240. package/core/host-contracts/abi-fragments/fragments.ts +69 -0
  241. package/core/key/FheEncryptionKeyCache-p.ts +92 -91
  242. package/core/key/copyFheEncryptionKeyBytes-p.ts +23 -0
  243. package/core/key/ensureFheEncryptionKeyDownload.ts +293 -0
  244. package/core/key/fetchFheEncryptionKey.ts +8 -35
  245. package/core/key/fetchFheEncryptionKeyBytes.ts +7 -56
  246. package/core/key/verifyFheEncryptionKeyBytes-p.ts +452 -0
  247. package/core/modules/encrypt/mock.ts +4 -149
  248. package/core/modules/encrypt/module/api-p.ts +1 -126
  249. package/core/modules/encrypt/module/index.ts +0 -12
  250. package/core/modules/encrypt/types.ts +2 -57
  251. package/core/modules/relayer/cleartext/mock.ts +1 -0
  252. package/core/modules/relayer/module/RelayerAsyncRequest.ts +11 -2
  253. package/core/modules/relayer/module/fetchFheEncryptionKeySource.ts +12 -4
  254. package/core/modules/relayer/module/relayerUrl.ts +52 -1
  255. package/core/modules/relayer/types.ts +9 -1
  256. package/core/runtime/CoreFhevm-p.ts +159 -21
  257. package/core/types/coreFhevmClient.ts +33 -4
  258. package/core/types/fhevmChain.ts +7 -0
  259. package/core/types/hostContract.ts +2 -0
  260. package/core/types/index.ts +1 -0
  261. package/core/types/relayer.ts +6 -0
  262. package/core/types/zkProofBuilder-p.ts +2 -1
  263. package/ethers/cleartext/createFhevmCleartextBaseClient.ts +1 -1
  264. package/ethers/cleartext/createFhevmCleartextClient.ts +1 -1
  265. package/ethers/cleartext/createFhevmCleartextDecryptClient.ts +1 -1
  266. package/ethers/cleartext/createFhevmCleartextEncryptClient.ts +1 -1
  267. package/ethers/clients/createFhevmBaseClient.ts +1 -1
  268. package/ethers/clients/createFhevmClient.ts +2 -2
  269. package/ethers/clients/createFhevmDecryptClient.ts +7 -3
  270. package/ethers/clients/createFhevmEncryptClient.ts +2 -2
  271. package/package.json +1 -1
  272. package/viem/cleartext/createFhevmCleartextBaseClient.ts +1 -1
  273. package/viem/cleartext/createFhevmCleartextClient.ts +1 -1
  274. package/viem/cleartext/createFhevmCleartextDecryptClient.ts +1 -1
  275. package/viem/cleartext/createFhevmCleartextEncryptClient.ts +1 -1
  276. package/viem/clients/createFhevmBaseClient.ts +1 -1
  277. package/viem/clients/createFhevmClient.ts +2 -2
  278. package/viem/clients/createFhevmDecryptClient.ts +7 -3
  279. package/viem/clients/createFhevmEncryptClient.ts +2 -2
  280. package/_cjs/core/key/serializeFheEncryptionKey.js +0 -25
  281. package/_cjs/core/key/serializeFheEncryptionKey.js.map +0 -1
  282. package/_esm/core/key/serializeFheEncryptionKey.js +0 -24
  283. package/_esm/core/key/serializeFheEncryptionKey.js.map +0 -1
  284. package/_types/core/key/serializeFheEncryptionKey.d.ts +0 -6
  285. package/_types/core/key/serializeFheEncryptionKey.d.ts.map +0 -1
  286. package/core/key/serializeFheEncryptionKey.ts +0 -42
@@ -41,6 +41,8 @@ export class CacheEntryImpl implements CacheEntry {
41
41
 
42
42
  /** @internal promise on the future value being resolved. Do not use externally. */
43
43
  _pending!: Promise<FheEncryptionKeyBytes | FheEncryptionKeyWasm>;
44
+ /** @internal promise on the bytes as fetched, kept after conversion to wasm. Do not use externally. */
45
+ _bytes!: Promise<FheEncryptionKeyBytes>;
44
46
  /** @internal debug: true if `_pending` has been chained from (e.g. by ensureWasm). */
45
47
  _pendingChained: boolean;
46
48
 
@@ -82,28 +84,31 @@ function _assertWasmIsTerminal(entry: CacheEntry): void {
82
84
  /**
83
85
  * Global cache for FHE public key parameters.
84
86
  *
85
- * Keyed by relayer URL. Each entry is a live mutable placeholder that callers
86
- * hold a reference to and observe state changes across awaits.
87
+ * Keyed by slot: the relayer URL, then the KMSGeneration contract the key
88
+ * is checked against, or `unverified` for never-verified keys (see
89
+ * {@link getFheEncryptionKeySlot}). Each entry is a
90
+ * live mutable placeholder that callers hold a reference to and observe state
91
+ * changes across awaits.
87
92
  */
88
93
  export class FheEncryptionKeyCache {
89
94
  readonly #cache = new Map<string, CacheEntryImpl>();
90
95
 
91
96
  ////////////////////////////////////////////////////////////////////////////////
92
97
 
93
- get(relayerUrl: string): CacheEntry | undefined {
94
- return this.#cache.get(relayerUrl);
98
+ get(slot: string): CacheEntry | undefined {
99
+ return this.#cache.get(slot);
95
100
  }
96
101
 
97
- has(relayerUrl: string): boolean {
98
- return this.#cache.has(relayerUrl);
102
+ has(slot: string): boolean {
103
+ return this.#cache.has(slot);
99
104
  }
100
105
 
101
- remove(relayerUrl: string): boolean {
102
- const entry = this.#cache.get(relayerUrl);
106
+ remove(slot: string): boolean {
107
+ const entry = this.#cache.get(slot);
103
108
  if (entry !== undefined) {
104
109
  this.#invalidate(entry);
105
110
  }
106
- return this.#cache.delete(relayerUrl);
111
+ return this.#cache.delete(slot);
107
112
  }
108
113
 
109
114
  clear(): void {
@@ -113,6 +118,16 @@ export class FheEncryptionKeyCache {
113
118
  this.#cache.clear();
114
119
  }
115
120
 
121
+ /**
122
+ * Empties the slot if it still holds `entry`. Unlike `remove`, the entry is
123
+ * not invalidated: callers holding it finish with it.
124
+ */
125
+ evict(slot: string, entry: CacheEntry): void {
126
+ if (this.#cache.get(slot) === entry) {
127
+ this.#cache.delete(slot);
128
+ }
129
+ }
130
+
116
131
  /** Stale-ify an entry so in-flight callbacks hit the guard and get swallowed. */
117
132
  #invalidate(entry: CacheEntryImpl): void {
118
133
  entry.ready = Promise.resolve();
@@ -122,19 +137,42 @@ export class FheEncryptionKeyCache {
122
137
 
123
138
  ////////////////////////////////////////////////////////////////////////////////
124
139
 
125
- setBytes(owner: FhevmRuntime, relayerUrl: string, bytes: FheEncryptionKeyBytes): void {
126
- // First write wins: if an entry already exists (resolved or in-flight),
127
- // skip to avoid creating a closure over the 50MB bytes unnecessarily.
128
- if (this.#cache.has(relayerUrl)) {
140
+ /**
141
+ * Stores bytes in an empty slot, unchecked: callers check them first.
142
+ * First write wins: an existing entry (resolved or in-flight) is kept.
143
+ * For tests only (e.g. the browser smoke harness).
144
+ */
145
+ setBytes(owner: FhevmRuntime, slot: string, relayerUrl: string, bytes: FheEncryptionKeyBytes): void {
146
+ // Skip to avoid creating a closure over the key bytes unnecessarily.
147
+ if (this.#cache.has(slot)) {
129
148
  return;
130
149
  }
131
150
  _assertRelayerUrlMatch(bytes.metadata.relayerUrl, relayerUrl);
132
151
  // The closure over `bytes` is ephemeral: ensureBytes calls the fetcher
133
152
  // immediately, the promise resolves synchronously, and the closure becomes
134
- // unreachable. No extra copy of the 50MB data is retained.
153
+ // unreachable. The entry keeps `bytes` itself (not a copy), as served.
135
154
  this.ensureBytes({
136
155
  owner,
137
- relayerUrl,
156
+ slot,
157
+ fetcher: () => Promise.resolve(bytes),
158
+ metadata: bytes.metadata,
159
+ });
160
+ }
161
+
162
+ /**
163
+ * Stores bytes in the slot, replacing any entry, unchecked: callers check
164
+ * them first. A new entry object takes the slot, so callers holding the old
165
+ * entry finish with the old key.
166
+ *
167
+ * @returns the new entry.
168
+ */
169
+ replaceBytes(owner: FhevmRuntime, slot: string, relayerUrl: string, bytes: FheEncryptionKeyBytes): CacheEntry {
170
+ // Before emptying the slot: a mismatch leaves the cache as is.
171
+ _assertRelayerUrlMatch(bytes.metadata.relayerUrl, relayerUrl);
172
+ this.#cache.delete(slot);
173
+ return this.ensureBytes({
174
+ owner,
175
+ slot,
138
176
  fetcher: () => Promise.resolve(bytes),
139
177
  metadata: bytes.metadata,
140
178
  });
@@ -143,23 +181,26 @@ export class FheEncryptionKeyCache {
143
181
  ////////////////////////////////////////////////////////////////////////////////
144
182
 
145
183
  /**
146
- * Ensures the cache has an entry for the given relayer URL.
184
+ * Ensures the cache has an entry for the given slot.
147
185
  *
148
186
  * **First write wins**: if an entry already exists (resolved or in-flight,
149
187
  * bytes or wasm), it is kept as-is and the fetcher is never called.
150
188
  * Only when no entry exists is the fetcher invoked to start a new fetch.
151
189
  *
152
- * To force a re-fetch, call `remove(relayerUrl)` before `ensureBytes`.
190
+ * To force a re-fetch, call `remove(slot)` before `ensureBytes`.
191
+ *
192
+ * @returns the slot's entry, kept or new.
153
193
  */
154
194
  ensureBytes(parameters: {
155
195
  readonly owner: FhevmRuntime;
156
- readonly relayerUrl: string;
196
+ readonly slot: string;
157
197
  readonly fetcher: () => Promise<FheEncryptionKeyBytes>;
158
198
  readonly metadata: FheEncryptionKeyMetadata;
159
- }): void {
160
- const { owner, relayerUrl, fetcher, metadata } = parameters;
161
- if (this.#cache.has(relayerUrl)) {
162
- return;
199
+ }): CacheEntry {
200
+ const { owner, slot, fetcher, metadata } = parameters;
201
+ const existing = this.#cache.get(slot);
202
+ if (existing !== undefined) {
203
+ return existing;
163
204
  }
164
205
 
165
206
  const entry = new CacheEntryImpl(owner, metadata);
@@ -168,9 +209,11 @@ export class FheEncryptionKeyCache {
168
209
  entry.pendingKind = 'bytes';
169
210
  entry.pendingOp = 'fetching';
170
211
  entry._pending = pendingValue;
171
- entry.ready = this.#makeReady(relayerUrl, entry, 'bytes', pendingValue);
212
+ entry._bytes = pendingValue;
213
+ entry.ready = this.#makeReady(slot, entry, 'bytes', pendingValue);
172
214
 
173
- this.#cache.set(relayerUrl, entry);
215
+ this.#cache.set(slot, entry);
216
+ return entry;
174
217
  }
175
218
 
176
219
  ////////////////////////////////////////////////////////////////////////////////
@@ -180,18 +223,19 @@ export class FheEncryptionKeyCache {
180
223
  * If already wasm (pending or resolved), returns the existing entry.
181
224
  * Chains from `_pending` so it works whether bytes are resolved or still pending.
182
225
  * Idempotent: repeated calls return the same entry.
226
+ *
227
+ * Upgrades `entry`, the one the caller checked, even if another entry has
228
+ * taken the `slot` since.
183
229
  */
184
230
  ensureWasm(parameters: {
185
231
  readonly owner: FhevmRuntime;
186
- readonly relayerUrl: string;
232
+ readonly slot: string;
233
+ readonly entry: CacheEntry;
187
234
  readonly deserializeFn: (bytes: FheEncryptionKeyBytes) => Promise<FheEncryptionKeyWasm>;
188
235
  }): void {
189
- const { relayerUrl, deserializeFn } = parameters;
190
-
191
- const entry = this.#cache.get(relayerUrl);
192
- if (entry === undefined) {
193
- return;
194
- }
236
+ const { slot, deserializeFn } = parameters;
237
+ // Entries only come from this cache.
238
+ const entry = parameters.entry as CacheEntryImpl;
195
239
 
196
240
  if (entry.resolvedKind === 'wasm' || entry.pendingKind === 'wasm') {
197
241
  return;
@@ -212,65 +256,19 @@ export class FheEncryptionKeyCache {
212
256
  entry.pendingKind = 'wasm';
213
257
  entry.pendingOp = 'converting';
214
258
  entry._pending = pendingValue;
215
- entry.ready = this.#makeReady(relayerUrl, entry, 'wasm', pendingValue);
259
+ entry.ready = this.#makeReady(slot, entry, 'wasm', pendingValue);
216
260
  }
217
261
 
218
262
  /**
219
- * Get bytes from the cache, converting from wasm if necessary.
263
+ * The bytes of `entry`, as fetched, whether or not it still holds its slot.
220
264
  *
221
- * - No entry → `undefined`
222
- * - Resolved bytes → return immediately
223
- * - Resolved wasm → serialize to bytes and return
224
- * - Pending bytes → await, return resolved bytes
225
- * - Pending wasm → await, serialize to bytes and return
265
+ * Never serializes the wasm value back to bytes: tfhe upgrades older
266
+ * serialization versions on load, so the result could differ from the
267
+ * bytes the relayer served.
226
268
  */
227
- async resolveBytes(parameters: {
228
- readonly relayerUrl: string;
229
- readonly serializeFn?: ((parameters: FheEncryptionKeyWasm) => Promise<FheEncryptionKeyBytes>) | undefined;
230
- }): Promise<FheEncryptionKeyBytes | undefined> {
231
- const { relayerUrl, serializeFn } = parameters;
232
-
233
- const entry = this.#cache.get(relayerUrl);
234
- if (entry === undefined) {
235
- return undefined;
236
- }
237
-
238
- // Bytes already available — return immediately, don't wait for pending wasm
239
- if (entry.resolvedKind === 'bytes') {
240
- return entry.value as FheEncryptionKeyBytes;
241
- }
242
-
243
- // Wasm already available — serialize to bytes
244
- if (entry.resolvedKind === 'wasm') {
245
- if (serializeFn === undefined) {
246
- throw new Error('Cannot convert wasm to bytes: serialize function not provided');
247
- }
248
- return serializeFn(entry.value as FheEncryptionKeyWasm);
249
- }
250
-
251
- if (entry.pendingKind === undefined) {
252
- return undefined;
253
- }
254
-
255
- await entry.ready;
256
-
257
- // Re-read after potential await — entry is mutable across await boundaries.
258
- // Cast needed: TS narrows out "bytes" from the early return above,
259
- // but the entry can become "bytes" during the await.
260
- const kind = entry.resolvedKind as 'bytes' | 'wasm' | undefined;
261
-
262
- if (kind === 'bytes') {
263
- return entry.value as FheEncryptionKeyBytes;
264
- }
265
-
266
- if (kind === 'wasm') {
267
- if (serializeFn === undefined) {
268
- throw new Error('Cannot convert wasm to bytes: serialize function not provided');
269
- }
270
- return serializeFn(entry.value as FheEncryptionKeyWasm);
271
- }
272
-
273
- return undefined;
269
+ entryBytes(entry: CacheEntry): Promise<FheEncryptionKeyBytes> {
270
+ // Entries only come from this cache.
271
+ return (entry as CacheEntryImpl)._bytes;
274
272
  }
275
273
 
276
274
  ////////////////////////////////////////////////////////////////////////////////
@@ -280,7 +278,7 @@ export class FheEncryptionKeyCache {
280
278
  * self-evicts on rejection (if still current), and swallows stale errors.
281
279
  */
282
280
  #makeReady(
283
- relayerUrl: string,
281
+ slot: string,
284
282
  entry: CacheEntryImpl,
285
283
  resolvedKind: 'bytes' | 'wasm',
286
284
  pendingValue: Promise<FheEncryptionKeyBytes | FheEncryptionKeyWasm>,
@@ -294,9 +292,9 @@ export class FheEncryptionKeyCache {
294
292
  if (entry.ready !== ready) {
295
293
  return; // stale: a newer operation replaced us
296
294
  }
297
- // Verify the resolved value's metadata matches the cache key.
295
+ // Verify the resolved value's metadata matches the entry's relayer.
298
296
  // Catches bugs where a fetcher/deserializer returns data for a different relayer.
299
- _assertRelayerUrlMatch(resolved.metadata.relayerUrl, relayerUrl);
297
+ _assertRelayerUrlMatch(resolved.metadata.relayerUrl, entry.metadata.relayerUrl);
300
298
  entry.resolvedKind = resolvedKind;
301
299
  entry.value = resolved;
302
300
  entry.pendingKind = undefined;
@@ -311,18 +309,21 @@ export class FheEncryptionKeyCache {
311
309
  entry.pendingKind = undefined;
312
310
  entry.pendingOp = undefined;
313
311
  // Self-evict
314
- if (this.#cache.get(relayerUrl) === entry) {
315
- this.#cache.delete(relayerUrl);
312
+ if (this.#cache.get(slot) === entry) {
313
+ this.#cache.delete(slot);
316
314
  }
317
315
  entry.owner
318
316
  .deref()
319
317
  ?.config.logger?.error?.(
320
- `FheEncryptionKeyCache: ${resolvedKind === 'bytes' ? 'fetch' : 'conversion to wasm'} failed for relayerUrl="${relayerUrl}". Evicting cache entry; the next call will re-fetch.`,
318
+ `FheEncryptionKeyCache: ${resolvedKind === 'bytes' ? 'fetch' : 'conversion to wasm'} failed for slot="${slot}". Evicting cache entry; the next call will re-fetch.`,
321
319
  err,
322
320
  );
323
321
  throw err;
324
322
  },
325
323
  );
324
+ // Callers get the error through `_bytes` or by awaiting `ready`: never
325
+ // leave `ready` unhandled when no one awaits it.
326
+ ready.catch(() => undefined);
326
327
  return ready;
327
328
  }
328
329
  }
@@ -0,0 +1,23 @@
1
+ import type { FheEncryptionKeyBytes } from '../types/fheEncryptionKey.js';
2
+
3
+ ////////////////////////////////////////////////////////////////////////////////
4
+
5
+ /**
6
+ * A copy of the key and CRS bytes, so the verified bytes and the caller's
7
+ * arrays never share a buffer: changing one never changes the other.
8
+ * `new Uint8Array(…)` always copies, even a Node.js `Buffer` (whose `slice`
9
+ * is a view).
10
+ */
11
+ export function copyFheEncryptionKeyBytes(fheEncryptionKey: FheEncryptionKeyBytes): FheEncryptionKeyBytes {
12
+ return {
13
+ publicKeyBytes: {
14
+ ...fheEncryptionKey.publicKeyBytes,
15
+ bytes: new Uint8Array(fheEncryptionKey.publicKeyBytes.bytes),
16
+ },
17
+ crsBytes: {
18
+ ...fheEncryptionKey.crsBytes,
19
+ bytes: new Uint8Array(fheEncryptionKey.crsBytes.bytes),
20
+ },
21
+ metadata: { ...fheEncryptionKey.metadata },
22
+ };
23
+ }
@@ -0,0 +1,293 @@
1
+ import type { FhevmRuntime } from '../types/coreFhevmRuntime.js';
2
+ import type { FhevmChain } from '../types/fhevmChain.js';
3
+ import type { FhevmBase, OptionalNativeClient, ResolvedFhevmOptions } from '../types/coreFhevmClient.js';
4
+ import type { FheEncryptionKeyBytes } from '../types/fheEncryptionKey.js';
5
+ import type { RelayerKeyUrlOptions } from '../types/relayer.js';
6
+ import type { FetchFheEncryptionKeyBytesParameters } from '../modules/relayer/types.js';
7
+ import type { FhevmClientFrozenContext } from '../types/fhevmClientFrozenContext-p.js';
8
+ import type { CacheEntry } from './FheEncryptionKeyCache-p.js';
9
+ import { unsafeBytesEquals } from '../base/bytes.js';
10
+ import { FheEncryptionKeyVerificationError } from '../errors/FheEncryptionKeyVerificationError.js';
11
+ import {
12
+ getProvidedFheEncryptionKey,
13
+ getProvidedFheEncryptionKeyError,
14
+ releaseProvidedFheEncryptionKey,
15
+ } from '../runtime/CoreFhevm-p.js';
16
+ import { globalFheEncryptionKeyCache } from './FheEncryptionKeyCache-p.js';
17
+ import {
18
+ requiresKeyVerification,
19
+ resolveKmsGeneration,
20
+ verifyFheEncryptionKeyBytes,
21
+ } from './verifyFheEncryptionKeyBytes-p.js';
22
+
23
+ ////////////////////////////////////////////////////////////////////////////////
24
+
25
+ type Context = FhevmBase<FhevmChain, FhevmRuntime, OptionalNativeClient>;
26
+
27
+ /** A cache entry and its bytes, checked for the client. */
28
+ type ClientFheEncryptionKey = {
29
+ readonly slot: string;
30
+ readonly entry: CacheEntry;
31
+ readonly bytes: FheEncryptionKeyBytes;
32
+ };
33
+
34
+ ////////////////////////////////////////////////////////////////////////////////
35
+
36
+ /**
37
+ * The client's slot in the global key cache: the relayer URL, then what the
38
+ * key is checked against:
39
+ * - `<relayer URL>|kmsgen:<chain id>:<address>`: the KMSGeneration contract;
40
+ * - `<relayer URL>|unverified`: nothing (see
41
+ * `skipsFheEncryptionKeyVerification`); clients that check keys never
42
+ * read it.
43
+ *
44
+ * Clients share a slot only when they name the same relayer and
45
+ * KMSGeneration, so a wrong setting evicts only its own slot. A client
46
+ * whose RPC returns other state for that same contract (e.g. a fork)
47
+ * still shares the slot and can evict it. Neither suffix contains `|`, so
48
+ * two different slots never give the same string.
49
+ *
50
+ * @throws {FhevmConfigError} when the client cannot check key material.
51
+ * @internal
52
+ */
53
+ export function getFheEncryptionKeySlot(context: {
54
+ readonly chain: FhevmChain;
55
+ readonly runtime: FhevmRuntime;
56
+ readonly options: Pick<ResolvedFhevmOptions, 'keyVerification'>;
57
+ }): string {
58
+ const relayerUrl = context.chain.fhevm.relayerUrl;
59
+ if (!requiresKeyVerification(context.runtime)) {
60
+ return `${relayerUrl}|unverified`;
61
+ }
62
+ const { chainId, address } = resolveKmsGeneration(context);
63
+ return `${relayerUrl}|kmsgen:${chainId}:${address}`;
64
+ }
65
+
66
+ /**
67
+ * Starts the FHE encryption key download into the global cache, or joins the
68
+ * one in flight, then checks the key against `KMSGeneration` for this client,
69
+ * with its own settings (once per client and key). Builds the relayer request
70
+ * (e.g. auth) for both the bytes and the encryption paths. Does not convert
71
+ * the key.
72
+ *
73
+ * A caller-provided key (`options.fheEncryptionKey`) replaces the download:
74
+ * - equal to the cached key, once downloaded: the cached key is used, checked
75
+ * for this client;
76
+ * - otherwise (including while a download is in flight): checked, then cached,
77
+ * replacing a cached key, which is stale (only one key is active at a time),
78
+ * unless the cache holds the same key by then: that one is used, as above.
79
+ *
80
+ * Outcomes of the check:
81
+ * - pass: a provided key is cached and the client releases it;
82
+ * - {@link FheEncryptionKeyVerificationError}: a downloaded key leaves the
83
+ * cache, the next call downloads again; the client drops a provided key and
84
+ * keeps only the error: later calls throw it, with no RPC call and no
85
+ * download;
86
+ * - any other error (e.g. network): the key stays as is, the next call checks
87
+ * it again.
88
+ *
89
+ * Callers use the returned entry, the one checked, never the slot's current
90
+ * one: another entry may have taken the slot since.
91
+ *
92
+ * @throws {FhevmConfigError} when the client cannot check key material.
93
+ * @throws {FheEncryptionKeyVerificationError} when the key fails the check.
94
+ * @internal
95
+ */
96
+ export async function ensureFheEncryptionKeyDownload(
97
+ context: Context,
98
+ parameters: {
99
+ readonly fhevmContext: FhevmClientFrozenContext;
100
+ readonly options?: RelayerKeyUrlOptions | undefined;
101
+ readonly ignoreCache?: boolean | undefined;
102
+ },
103
+ ): Promise<ClientFheEncryptionKey> {
104
+ const relayerUrl = context.chain.fhevm.relayerUrl;
105
+ const runtime = context.runtime;
106
+ const logger = runtime.config.logger;
107
+ // A provided key that failed the check: only its error is left.
108
+ const providedError = getProvidedFheEncryptionKeyError(context);
109
+ if (providedError !== undefined) {
110
+ throw providedError;
111
+ }
112
+
113
+ // Checks the client's own setup, even when another client filled the cache.
114
+ const slot = getFheEncryptionKeySlot(context);
115
+
116
+ const provided = getProvidedFheEncryptionKey(context);
117
+ if (provided !== undefined) {
118
+ return _useProvidedFheEncryptionKey(context, provided, slot);
119
+ }
120
+
121
+ // Caller-provided options override runtime config defaults (e.g. auth)
122
+ const relayerParameters: FetchFheEncryptionKeyBytesParameters = {
123
+ ...parameters,
124
+ options: { auth: context.runtime.config.auth, ...parameters.options },
125
+ };
126
+
127
+ // Shared by every client on the slot: a download in flight is joined, and
128
+ // runs with the request options (e.g. auth, abort signal, retries) of the
129
+ // client that started it.
130
+ const entry = globalFheEncryptionKeyCache.ensureBytes({
131
+ owner: runtime,
132
+ slot,
133
+ fetcher: async () => {
134
+ logger?.debug?.(
135
+ `Fetching FHE encryption key/CRS bytes from relayer "${relayerUrl}" (chainId=${context.chain.id}).`,
136
+ );
137
+ try {
138
+ const bytes = await runtime.relayer.fetchFheEncryptionKeyBytes(
139
+ { relayerUrl, chainId: context.chain.id },
140
+ relayerParameters,
141
+ );
142
+ logger?.debug?.(`Fetched FHE encryption key/CRS bytes from relayer "${relayerUrl}".`);
143
+ return bytes;
144
+ } catch (e) {
145
+ logger?.error?.(`Failed to fetch FHE encryption key/CRS bytes from relayer "${relayerUrl}".`, e);
146
+ throw e;
147
+ }
148
+ },
149
+ metadata: { chainId: context.chain.id, relayerUrl },
150
+ });
151
+
152
+ return _verifyCachedFheEncryptionKey(context, slot, entry);
153
+ }
154
+
155
+ ////////////////////////////////////////////////////////////////////////////////
156
+
157
+ // Each client's check of each key (bytes object): concurrent calls on a
158
+ // client share one set of KMSGeneration reads. A key that fails the check stays
159
+ // failed; any other error (e.g. network) is retried by the next call.
160
+ const clientVerifications = new WeakMap<FheEncryptionKeyBytes, WeakMap<Context, Promise<void>>>();
161
+
162
+ function _verifyFheEncryptionKeyBytesForClient(context: Context, bytes: FheEncryptionKeyBytes): Promise<void> {
163
+ if (!requiresKeyVerification(context.runtime)) {
164
+ return Promise.resolve();
165
+ }
166
+ const checks = clientVerifications.get(bytes) ?? new WeakMap<Context, Promise<void>>();
167
+ clientVerifications.set(bytes, checks);
168
+ return _memoize(checks, context, () => verifyFheEncryptionKeyBytes(context, bytes).then(() => undefined), true);
169
+ }
170
+
171
+ async function _verifyCachedFheEncryptionKey(
172
+ context: Context,
173
+ slot: string,
174
+ entry: CacheEntry,
175
+ ): Promise<ClientFheEncryptionKey> {
176
+ const bytes = await globalFheEncryptionKeyCache.entryBytes(entry);
177
+ try {
178
+ await _verifyFheEncryptionKeyBytesForClient(context, bytes);
179
+ } catch (e) {
180
+ if (e instanceof FheEncryptionKeyVerificationError) {
181
+ // Clients on this slot check against the same KMSGeneration, so they
182
+ // reject these bytes too (unless their RPC serves other chain state).
183
+ globalFheEncryptionKeyCache.evict(slot, entry);
184
+ }
185
+ throw e;
186
+ }
187
+ return { slot, entry, bytes };
188
+ }
189
+
190
+ ////////////////////////////////////////////////////////////////////////////////
191
+
192
+ // The use of each client's provided key (its own copy): concurrent calls on a
193
+ // client share the one in flight. A failed use is forgotten: the client keeps
194
+ // the error of a key that fails the check (see ensureFheEncryptionKeyDownload),
195
+ // any other error is retried by the next call.
196
+ const providedKeyUses = new WeakMap<FheEncryptionKeyBytes, Promise<ClientFheEncryptionKey>>();
197
+
198
+ function _useProvidedFheEncryptionKey(
199
+ context: Context,
200
+ provided: FheEncryptionKeyBytes,
201
+ slot: string,
202
+ ): Promise<ClientFheEncryptionKey> {
203
+ return _memoize(
204
+ providedKeyUses,
205
+ provided,
206
+ async (): Promise<ClientFheEncryptionKey> => {
207
+ try {
208
+ const cachedEntry = await _getSameCachedEntry(slot, provided);
209
+ let checked: ClientFheEncryptionKey;
210
+ if (cachedEntry !== undefined) {
211
+ checked = await _verifyCachedFheEncryptionKey(context, slot, cachedEntry);
212
+ } else {
213
+ await _verifyFheEncryptionKeyBytesForClient(context, provided);
214
+ // Another client may have cached the same key during the check: use
215
+ // its entry rather than orphan it.
216
+ const sameEntry = await _getSameCachedEntry(slot, provided);
217
+ if (sameEntry !== undefined) {
218
+ checked = await _verifyCachedFheEncryptionKey(context, slot, sameEntry);
219
+ } else {
220
+ const entry = globalFheEncryptionKeyCache.replaceBytes(
221
+ context.runtime,
222
+ slot,
223
+ context.chain.fhevm.relayerUrl,
224
+ provided,
225
+ );
226
+ checked = { slot, entry, bytes: provided };
227
+ }
228
+ }
229
+ // The cache holds the key from now on.
230
+ releaseProvidedFheEncryptionKey(context, provided);
231
+ return checked;
232
+ } catch (e) {
233
+ if (e instanceof FheEncryptionKeyVerificationError) {
234
+ // The client keeps only the error, not the bytes.
235
+ releaseProvidedFheEncryptionKey(context, provided, e);
236
+ }
237
+ throw e;
238
+ }
239
+ },
240
+ false,
241
+ );
242
+ }
243
+
244
+ /**
245
+ * The slot's entry if it holds `provided`'s bytes. Compared only with a cached
246
+ * key already downloaded: never waits for another client's download.
247
+ */
248
+ async function _getSameCachedEntry(slot: string, provided: FheEncryptionKeyBytes): Promise<CacheEntry | undefined> {
249
+ const entry = globalFheEncryptionKeyCache.get(slot);
250
+ if (entry?.resolvedKind === undefined) {
251
+ return undefined;
252
+ }
253
+ const cached = await globalFheEncryptionKeyCache.entryBytes(entry);
254
+ return _sameFheEncryptionKeyBytes(provided, cached) ? entry : undefined;
255
+ }
256
+
257
+ /**
258
+ * Memoizes `start()` under `key`: concurrent and later calls share it. A
259
+ * rejection is forgotten, so the next call starts again, except a
260
+ * {@link FheEncryptionKeyVerificationError} when `keepVerificationError`.
261
+ */
262
+ function _memoize<K extends object, T>(
263
+ memo: WeakMap<K, Promise<T>>,
264
+ key: K,
265
+ start: () => Promise<T>,
266
+ keepVerificationError: boolean,
267
+ ): Promise<T> {
268
+ const memoized = memo.get(key);
269
+ if (memoized !== undefined) {
270
+ return memoized;
271
+ }
272
+ const check = start();
273
+ memo.set(key, check);
274
+ check.catch((e: unknown) => {
275
+ if (!(keepVerificationError && e instanceof FheEncryptionKeyVerificationError) && memo.get(key) === check) {
276
+ memo.delete(key);
277
+ }
278
+ });
279
+ return check;
280
+ }
281
+
282
+ /**
283
+ * Ids aside: a label id and a 32-byte hex id can name the same bytes. The
284
+ * check against the active ids decides (a relayer serving the right bytes under
285
+ * a wrong id fails the check for clients reusing that entry).
286
+ */
287
+ function _sameFheEncryptionKeyBytes(a: FheEncryptionKeyBytes, b: FheEncryptionKeyBytes): boolean {
288
+ return (
289
+ a === b ||
290
+ (unsafeBytesEquals(a.publicKeyBytes.bytes, b.publicKeyBytes.bytes) &&
291
+ unsafeBytesEquals(a.crsBytes.bytes, b.crsBytes.bytes))
292
+ );
293
+ }