Client-side Blocklock Encryption

This guide provides detailed instructions on how to implement blocklock encryption requests from your client-side application using the blocklock-js library.

Overview

The blocklock-js library provides a convenient way to create and manage blocklock encryption requests from your client-side application. It handles the encryption process and provides utilities for interacting with the dcipher network.

Walkthrough

Step-1. Install and Initialize

First, install the blocklock-js library and initialize it for the specific network you are interacting with.

• Using Pre-configured Networks: For supported networks, you can use the convenient creation methods that automatically handle the BlocklockSender contract address and chain ID.

Here's how to use both approaches:

import { Blocklock } from 'blocklock-js';
import { ethers } from 'ethers';

// Initialize provider and signer
const provider = new ethers.JsonRpcProvider('YOUR_RPC_URL');
const signer = new ethers.Wallet('YOUR_PRIVATE_KEY', provider);

// Create Blocklock instance for a specific network
// The library handles the BlocklockSender address and chain ID internally
const blocklock = Blocklock.createBaseSepolia(signer);

Supported Networks

The blocklock-js library supports the following networks with convenient creation methods:

Network Name	Chain ID	Creation Method
Base Sepolia	84532	Blocklock.createBaseSepolia()
Polygon Mainnet	137	Blocklock.createPolygonPos()
Filecoin Mainnet	314	Blocklock.createFilecoinMainnet()
Filecoin Calibration	314159	Blocklock.createFilecoinCalibration()
Furnace Testnet	64630	Blocklock.createFurnace()
Avalanche Fuji(C-Chain) Testnet	43113	Blocklock.createAvalancheCChain()
Arbitrum Sepolia Testnet	421614	Blocklock.createOptimismSepolia()
OP Sepolia Testnet	11155420	Blocklock.createArbitrumSepolia()
Sei Devnet	713715	Blocklock.createSeiTestnet()

note

For the most up-to-date list of supported networks and their BlocklockSender contract addresses, check the Networks page.

Step-2. Prepare Your Data

Before creating a blocklock request, you need to prepare three key components:

1. Block Height Condition: The target block height when the ciphertext should be decryptable

2. Encoded Message: Your data encoded using solidity-decoder provided by blocklock-js

   a. Set Block Height Condition

   // Set target block height (e.g., 10 blocks from now)
   const targetBlock = BigInt(await ethers.provider.getBlockNumber() + 10);

   b. Encode Your Message

   The library offer encodeParams() to support encoding various Solidity data types, including uint256, address, string, bytes and bytes32.

   // Basic uint256 Type
   const msg = ethers.parseEther("1.0"); // 1 ETH
   
   // Encode the uint256 value
   const encoder = new SolidityEncoder();
   const msgBytes = encodeParams(["uint256"], [msg]);
   const encodedMessage = getBytes(msgBytes);

   The function returns a Ciphertext object that contains the encrypted data and will be used in your blocklock request.

Step-3. Create Blocklock Request

Create the blocklock request using the encryptAndRegister function. The function will automatically:

• encrypt the message with specified block height
• Calculate the required gas limit
• Determine the request price
• Handle the payment process
• Submit the request to the dcipher network using the preset blocklockSender contract.

// Create the request
const {id, ciphertext} = await blocklockjs.encryptAndRegister(encodedMessage, blockHeight);

Step-4. Track Request Status

Monitor the status of your blocklock request using requestId:

import { Blocklock, BlocklockStatus } from "blocklock-js";
import { BASE_SEPOLIA } from "blocklock-js/src/networks";

const [signer] = await ethers.getSigners();
//Call BlocklockSender to check if the request is inFlight
const blocklockSender = await ethers.getContractAt("IBlocklockSender", BASE_SEPOLIA.contractAddress, signer as unknown as Signer);
const isInFlight = await blocklockSender.isInFlight(requestId);

if(!isInFlight){
    //If not pending, retrieve the BlocklockStatus
    const blocklockjs = Blocklock.createBaseSepolia(signer as unknown as Signer);
    const result: BlocklockStatus = await blocklockjs.fetchBlocklockStatus(requestId);
    console.log(result);
}
else {
    console.log("Blocklock Request is pending");
}

Step-5. Decrypt the Data

Once the target block height is reached in the specified blockchain, the decryption key from dcipher network will be delivered so that you can decrypt the data:

import { Blocklock, SolidityDecoder, decodeParams } from "blocklock-js";

async function decryptBlocklockData(requestId: bigint, result: BlocklockStatus) {
    const decryptedBytes = await blocklockjs.decrypt(result.ciphertext, result.decryptionKey);

    // Convert Uint8Array to hex string
    const hexString = ethers.hexlify(decryptedBytes);
    // Example: Decode uint256
    const decodedValue = decodeParams(["uint256"], hexString);
    console.log("Decrypted value:", decodedValue);

    return decodedValue;
}

The decryption process involves:

1. Using blocklock.decrypt() to decrypt the data
2. Using decodeParams() to decode the decrypted bytes back to the original data type

note

Make sure to use the appropriate decoder method that matches the data type you originally encrypted.