{"id":43156710,"url":"https://github.com/randa-mu/blocklock-js","last_synced_at":"2026-02-01T00:39:26.127Z","repository":{"id":262104404,"uuid":"886231387","full_name":"randa-mu/blocklock-js","owner":"randa-mu","description":"A Typescript library for encrypting data that can't be decrypted until a future chain height has been reached. Compatible with a variety of blockchains.","archived":false,"fork":false,"pushed_at":"2025-12-01T14:52:42.000Z","size":1124,"stargazers_count":2,"open_issues_count":3,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-12-03T23:34:05.636Z","etag":null,"topics":["blockchain","blocklock","crypto","drand","ethereum","evm","timelock"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/randa-mu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-11-10T14:43:45.000Z","updated_at":"2025-12-01T14:52:49.000Z","dependencies_parsed_at":"2025-01-16T21:34:49.193Z","dependency_job_id":"3817d55a-bc96-4187-be9c-d098ec9e12e0","html_url":"https://github.com/randa-mu/blocklock-js","commit_stats":null,"previous_names":["randa-mu/blocklock-js"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/randa-mu/blocklock-js","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/randa-mu%2Fblocklock-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/randa-mu%2Fblocklock-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/randa-mu%2Fblocklock-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/randa-mu%2Fblocklock-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/randa-mu","download_url":"https://codeload.github.com/randa-mu/blocklock-js/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/randa-mu%2Fblocklock-js/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28962418,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-31T23:03:11.038Z","status":"ssl_error","status_checked_at":"2026-01-31T22:56:44.691Z","response_time":128,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blockchain","blocklock","crypto","drand","ethereum","evm","timelock"],"created_at":"2026-02-01T00:39:26.064Z","updated_at":"2026-02-01T00:39:26.117Z","avatar_url":"https://github.com/randa-mu.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"## blocklock-js\n\n`blocklock-js` is a TypeScript library that simplifies generating encrypted data off-chain for use with the dcrypt network. It allows developers to securely encrypt data tied to a user-defined condition, e.g., a future block height. This encrypted payload can then be referenced in on-chain timelock encryption requests via smart contracts. Once the specified block is mined, the decryption key is automatically delivered to the smart contract via a callback, enabling conditional data access on-chain.\n\nThe library also enables developers to track the status of a conditional encryption request.\n\n### On-Chain Integration\n\nSolidity interfaces and associated documentation can be found in the [blocklock-solidity](https://github.com/randa-mu/blocklock-solidity.git) repository.\n\n#### Smart Contract Addresses\n\n**BlocklockSender Proxy**\n\nA lightweight proxy contract that enables upgradeability for the `BlocklockSender` implementation. It delegates all calls to the underlying implementation and serves as the primary interface for user interaction.\n\n| Network                    | Address                                                                                                                     |\n|----------------------------|-----------------------------------------------------------------------------------------------------------------------------|\n| Filecoin Mainnet           | [0x34092470CC59A097d770523931E3bC179370B44b](https://filfox.info/en/address/0x34092470CC59A097d770523931E3bC179370B44b)     |\n| Filecoin Calibration Testnet | [0xF00aB3B64c81b6Ce51f8220EB2bFaa2D469cf702](https://calibration.filfox.info/en/address/0xF00aB3B64c81b6Ce51f8220EB2bFaa2D469cf702) |\n| Base Sepolia               | [0x82Fed730CbdeC5A2D8724F2e3b316a70A565e27e](https://sepolia.basescan.org/address/0x82Fed730CbdeC5A2D8724F2e3b316a70A565e27e) |\n| Polygon PoS                | [0x82Fed730CbdeC5A2D8724F2e3b316a70A565e27e](https://polygonscan.com/address/0x82Fed730CbdeC5A2D8724F2e3b316a70A565e27e)    |\n| Optimism Sepolia           | [0xd22302849a87d5B00f13e504581BC086300DA080](https://sepolia-optimism.etherscan.io/address/0xd22302849a87d5B00f13e504581BC086300DA080)    |\n| Arbitrum Sepolia           | [0xd22302849a87d5B00f13e504581BC086300DA080](https://sepolia.arbiscan.io/address/0xd22302849a87d5B00f13e504581BC086300DA080)    |\n| Avalanche (C-Chain) Testnet           | [0xd22302849a87d5B00f13e504581BC086300DA080](https://testnet.snowtrace.io/address/0xd22302849a87d5B00f13e504581BC086300DA080)    |\n| Sei Testnet           | [0xd22302849a87d5B00f13e504581BC086300DA080](https://seitrace.com/address/0xd22302849a87d5B00f13e504581BC086300DA080?chain=atlantic-2)    |\n\n\n**Other contract addresses**\nYou should only need the `BlocklockSender` proxy above, but a full list of contract addresses can be found in the [solidity repo's README](https://github.com/randa-mu/blocklock-solidity).\n\n\n### Installation\n\nTo install the library, install the latest version using:\n\n```sh\nnpm install blocklock-js\n```\n\n\n### Usage Example\n\n#### Prerequisites\n\n* [ethers](https://www.npmjs.com/package/ethers) for wallet setup and message encoding.\n* Node.js v22+\n\n#### Setup\n\n1. Create a `.env` file or set the following environment variables, e.g., for Filecoin mainnet:\n\n```bash\nRPC_URL=https://your-rpc-url\nPRIVATE_KEY=your_private_key\n```\n\n2. Install dependencies:\n\n```bash\nnpm install\n```\n\n\n#### Usage example\n\nThis example demonstrates encrypting a `uint256` value and using the Ciphertext and condition bytes in a user smart contract that implements the `createTimelockRequestWithDirectFunding` function to create a timelock encryption request on-chain. An example use case is a sealed-bid auction where bid amounts are encrypted and only decrypted at the auction ending block number.\n\nThe example user smart contract source code can be found [here](https://github.com/randa-mu/blocklock-solidity/blob/main/src/mocks/MockBlocklockReceiver.sol).\n\nThis script shows how to encrypt data with a future block as a condition\n\n\n```ts\nimport { createProvider, Blocklock, encodeCiphertextToSolidity, encodeCondition } from \"blocklock-js\"\nimport { Wallet, Provider, NonceManager, ethers, getBytes } from \"ethers\"\nimport { MockBlocklockReceiver__factory } from \"../types\"; // Users' solidity contract TypeScript binding\n\nasync function main() {\n  const rpc = createProvider(process.env.RPC_URL || \"\")\n  const wallet = new NonceManager(new Wallet(process.env.PRIVATE_KEY || \"\", rpc))\n  // Create a Blocklock instance for the Filecoin mainnet\n  const blocklock = Blocklock.createFilecoinMainnet(wallet)\n\n  // Value to encrypt (4 ETH as uint256)\n  const msg = ethers.utils.parseEther(\"4\");\n  const plaintext = Buffer.from(msg)\n  const currentBlock = await rpc.getBlockNumber()\n  const targetBlock = BigInt(currentBlock + 5)\n\n  console.log(`Encrypting for block ${targetBlock} (current: ${currentBlock})`)\n  const ciphertext = await blocklock.encrypt(plaintext, targetBlock)\n\n  // User contract\n  const mockBlocklockReceiver = MockBlocklockReceiver__factory.connect(\"user blocklcok receiver contract address\", wallet);\n\n  // Generate the timelock encryption condition bytes string\n  const conditionBytes = encodeCondition(targetBlock);\n  // Amount of gas users callback function is expected to consume, i.e., the function that will be called with the decryption key\n  const callbackGasLimit = 500_000;\n\n  // Compute the request price to pay for the direct funding request\n  const requestPrice = await blocklock.calculateRequestPriceNative(callbackGasLimit);\n\n  // Call `createTimelockRequestWithDirectFunding` on the user's contract \n  // for a direct or ad hoc funding request with the following parameters:\n  // uint32 callbackGasLimit, \n  // bytes calldata condition and,\n  // TypesLib.Ciphertext calldata encryptedData\n  const tx = await mockBlocklockReceiver\n    .connect(wallet)\n    .createTimelockRequestWithDirectFunding(callbackGasLimit, conditionBytes, encodeCiphertextToSolidity(ciphertext), \n    {value: requestPrice});\n  // Note: for subscription-based funding, \n  // use createTimelockRequestWithSubscription instead.\n\n  const receipt = await tx.wait(1);\n\n  if (!receipt) {\n    throw new Error(\"Transaction has not been mined\");\n  }\n\n  console.log(\"Timelock request created!\");\n}\n\nmain().catch((error) =\u003e {\n  console.error(\"Error:\", error);\n});\n```\n\n#### How It Works\n1. Encoding and Encryption:\n\n* Use blocklock-js to:\n\n  * Create a provider and signer using Wallet and NonceManager.\n\n  * Initialize a Blocklock instance for your target network (e.g., Filecoin mainnet).\n\n  * Prepare the message to encrypt (e.g., 4 ETH encoded as a uint256).\n\n  * Select a future block height as the decryption condition.\n\n  ```ts\n  const msg = ethers.utils.parseEther(\"4\");\n  const plaintext = Buffer.from(msg);\n  const currentBlock = await rpc.getBlockNumber();\n  const targetBlock = BigInt(currentBlock + 5);\n\n  const ciphertext = await blocklock.encrypt(plaintext, targetBlock);\n  const conditionBytes = encodeCondition(targetBlock);\n  ```\n\n2. On-Chain Interaction:  \n\n    * Use your own smart contract (e.g., `MockBlocklockReceiver`) to create a timelock encryption request.\n    * Call `createTimelockRequestWithDirectFunding`, which:\n\n      * Stores the encrypted data (Ciphertext) and decryption condition on-chain via the `BlocklockSender` contract.\n\n      * Funds the request by paying the `requestPrice` via the transaction.\n\n      * Generates a unique request ID.Call the appropriate function in the user contract with the encrypted data and the chain height used during off-chain encryption. \n\n      ```ts\n      const callbackGasLimit = 500_000;\n      \n      const requestPrice = await blocklock.calculateRequestPriceNative(callbackGasLimit);\n\n      await mockBlocklockReceiver.createTimelockRequestWithDirectFunding(\n        callbackGasLimit,\n        conditionBytes,\n        encodeCiphertextToSolidity(ciphertext),\n        {value: requestPrice}\n      );\n      ```\n\n3. Automatic Decryption and Callback:\n  * Once the specified condition is met (e.g., target block is mined):\n\n    * The `BlocklockSender` contract receives the decryption key from the dcipher Threshold Network.\n\n    * It automatically triggers a callback to the users contract with the key.\n\n    * The users contract can optionally call decrypt to recover the original message on-chain.\n\n\n### Common Errors\n\n#### Webpack Configuration\n\nWhen using the library in web applications, there might be webpack errors such as the one displayed below:\n\n![Webpack require error](./documentation/images/webpack-require.png)\n\n\nTo resolve this error, one solution is to update your `next.config.ts` configuration file if you use one with similar configurations for webpack below. \n\n```ts\nimport type { NextConfig } from \"next\";\n\nconst nextConfig: NextConfig = {\n  /* config options here */\n   webpack: (config) =\u003e {\n     config.externals.push({\n       'node:crypto': 'crypto',\n     });\n     return config;\n  },\n};\n\nexport default nextConfig;\n```\n\nIn the library's Webpack configuration, the following setting is used:\n\n```javascript\nexternals: {\n    'node:crypto': 'commonjs crypto',\n}\n```\n\nThis configuration tells the bundler **not to include the `crypto` module** in the final bundle. Instead, it treats `'node:crypto'` as an **external dependency** and expects it to be available in the runtime environment. `'commonjs crypto'` ensures that the module is required using the **CommonJS format**, making it compatible with Node.js. This ensures compatibility with environments where the `crypto` module is natively available.\n\n\n### Licensing\n\nThis library is licensed under the MIT License which can be accessed [here](LICENSE).\n\n### Contributing\n\nContributions are welcome! If you find a bug, have a feature request, or want to improve the code, feel free to open an issue or submit a pull request.\n\n### Acknowledgements\n\nSpecial thanks to the Filecoin Foundation for supporting the development of this library.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Franda-mu%2Fblocklock-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Franda-mu%2Fblocklock-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Franda-mu%2Fblocklock-js/lists"}