Add support for data encoding with unit tests and update Solidity interfaces

.github/workflows/build.yml

@@ -17,10 +17,10 @@ jobs:
           node-version: 22.3.0
 
       - name: Install dependencies
-        run: npm ci
+        run: yarn install
 
       - name: Test
-        run: npm run test
+        run: yarn test
 
       - name: Build
-        run: npm run build
+        run: yarn build

.gitmodules

@@ -1,3 +1,6 @@
 [submodule "contracts/lib/forge-std"]
 	path = contracts/lib/forge-std
 	url = https://github.com/foundry-rs/forge-std
+[submodule "contracts/lib/openzeppelin-contracts"]
+	path = contracts/lib/openzeppelin-contracts
+	url = https://github.com/OpenZeppelin/openzeppelin-contracts

README.md

@@ -1,10 +1,129 @@
 ## @randamu/blocklock-js
 
-A convenience library for encrypting data for the dcrypt network to dcrypt based on conditions you set.
+BlocklockJS is a TypeScript library designed to simplify the process of generating encrypted data off-chain for the dcrypt network. It enables developers to securely encrypt data tied to a user-specified future block number. The encrypted data can then be used to create on-chain timelock encryption requests in smart contracts. Once the specified block number is mined, the user’s smart contract will receive the decryption keys automatically.
 
-Build everything by running `npm run build`. This creates an `index.js` and `index.d.ts` at the root directory.
 
-Solidity interfaces for encryption and decryption can be found in the [contracts](./contracts) directory.
+### Key Capabilities
 
-## Documentation
-You can find the docs [on our docs website](https://dcrypt.network/docs/features/blocklock)
+Using this library, developers can:
+
+* Encode and encrypt various Solidity-compatible data types.
+* Encrypt the encoded data off-chain using a public key, which can then be integrated into smart contracts for timelock encryption requests.
+
+
+### On-Chain Integration
+
+Solidity interfaces used for on-chain decryption requests can be found in the [contracts](./contracts) directory and the documentation for the solidity interfaces can be found in the [blocklock-solidity](github.com/randa-mu/blocklock-solidity.git) repository.
+
+#### Smart Contract Addresses
+
+| Contract        | Address | Network          |
+|-----------------|---------|------------------|
+| BlocklockSender Proxy | 0xfF66908E1d7d23ff62791505b2eC120128918F44   | Filecoin Testnet |
+
+
+### Build Instructions
+
+To build the library, run the following command:
+
+```sh
+npm run build
+```
+
+This creates an `index.js` and `index.d.ts` at the root directory.
+
+### Usage Example
+
+Here’s how to use BlocklockJS to encrypt data and create an on-chain timelock encryption request.
+
+#### Example: Encrypting a uint256 (4 ETH) for Decryption 2 Blocks Later
+
+This example demonstrates encrypting a uint256 value and sending it to a user smart contract that implements the createTimelockRequest function. In a different use case, e.g., sealed bid auction, this could be refactored into a `sealedBid` function.
+The example user smart contract source code can be found [here](contracts/src/mocks/MockBlocklockReceiver.sol).
+
+```js
+import { ethers, getBytes } from "ethers";
+import { Blocklock, SolidityEncoder, encodeCiphertextToSolidity } from "blocklockjs";
+import { MockBlocklockReceiver__factory } from "../types"; // Generated by Typechain
+
+async function main() {
+  // User wallet
+  const wallet = new ethers.Wallet("your-private-key", ethers.provider);
+  // User contract
+  const mockBlocklockReceiver = MockBlocklockReceiver__factory.connect("user blocklcok receiver contract address", wallet);
+
+  // Ensure plainTextValue is initially 0
+  console.log("Initial plainTextValue:", (await mockBlocklockReceiver.plainTextValue()).toString());
+
+  // Set block height (current block + 2)
+  const blockHeight = BigInt(await ethers.provider.getBlockNumber() + 2);
+
+  // Value to encrypt (4 ETH as uint256)
+  const msg = ethers.utils.parseEther("4");
+
+  // Encode the uint256 value
+  const encoder = new SolidityEncoder();
+  const msgBytes = encoder.encodeUint256(msg);
+  const encodedMessage = getBytes(msgBytes);
+
+  // Encrypt the encoded message
+  const blocklockjs = new Blocklock(wallet, "blocklockSender contract address");
+  const ciphertext = blocklockjs.encrypt(encodedMessage, blockHeight);
+
+  // Call `createTimelockRequest` on the user's contract
+  const tx = await mockBlocklockReceiver
+    .connect(wallet)
+    .createTimelockRequest(blockHeight, encodeCiphertextToSolidity(ciphertext));
+  const receipt = await tx.wait(1);
+
+  if (!receipt) {
+    throw new Error("Transaction has not been mined");
+  }
+
+  console.log("Timelock request created!");
+}
+
+main().catch((error) => {
+  console.error("Error:", error);
+});
+```
+
+#### How It Works
+1. Encoding and Encryption:
+
+    * Use the SolidityEncoder to encode Solidity-compatible data types.
+    * Encrypt the encoded message and specify the decryption block number.
+
+2. On-Chain Interaction:
+
+    * Call the appropriate function in the user contract with the encrypted data and the block number used during off-chain encryption. In this example, the function `createTimelockRequest` is called, which creates an on-chain timelock request with the encrypted data and block number as a condition for decryption, stores the encrypted data, and generates a request ID.
+
+3. Decryption:
+
+    * After the specified block number, the on-chain timelock contract triggers a callback to the user's contract, providing the decryption key. The user's contract then calls the `decrypt` function in the `BlocklockSender` contract to perform on-chain decryption using the provided decryption key.
+
+
+### Supported Data Types
+The library supports encoding and encryption of the following Solidity-compatible data types:
+
+* uint256
+* int256
+* address
+* string
+* bytes
+* bytes32
+
+Use the `SolidityEncoder` to encode any of these types before encryption.
+
+
+### Licensing
+
+This library is licensed under the MIT License which can be accessed [here](LICENSE).
+
+### Contributing
+
+Contributions 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.
+
+### Acknowledgments
+
+Special thanks to the Filecoin Foundation for supporting the development of this library.

contracts/src/AbstractBlocklockReceiver.sol

@@ -1,15 +1,20 @@
 // SPDX-License-Identifier: MIT
 pragma solidity 0.8.24;
 
-import {IBlocklockReceiver} from "./IBlocklockReceiver.sol";
+import {IBlocklockReceiver} from "./interfaces/IBlocklockReceiver.sol";
+import {IBlocklockSender} from "./interfaces/IBlocklockSender.sol";
 
 abstract contract AbstractBlocklockReceiver is IBlocklockReceiver {
-    address public immutable DECRYPTION_PROVIDER = 0x11045878Ed62Ec3aCC91cE36A46F4EF61d4616e1;
+    IBlocklockSender public blocklock;
 
-    error NotAuthorizedDecryptionProvider();
-
-    modifier onlyDecryptionProvider(){
-        if (msg.sender != DECRYPTION_PROVIDER) revert NotAuthorizedDecryptionProvider();
+    modifier onlyBlocklockContract() {
+        require(msg.sender == address(blocklock), "Only timelock contract can call this.");
         _;
     }
+
+    constructor(address blocklockSender) {
+        blocklock = IBlocklockSender(blocklockSender);
+    }
+
+    function receiveBlocklock(uint256 requestID, bytes calldata decryptionKey) external virtual onlyBlocklockContract {}
 }