Complete Web2JSON Guide: From Setup to Production

# Clone the official Flare Hardhat starter
git clone https://github.com/flare-foundation/flare-hardhat-starter
cd flare-hardhat-starter

# Install all dependencies
npm install

# .env - Fill in these values
PRIVATE_KEY=0xYourPrivateKeyHere
COSTON2_RPC_URL=https://coston2-api.flare.network/ext/C/rpc
FLARE_RPC_URL=https://flare-api.flare.network/ext/C/rpc
VERIFIER_API_KEY_TESTNET=00000000-0000-0000-0000-000000000000
ATTESTATION_PROVIDER_URL_TESTNET="https://web2json-verifier-test.flare.rocks/"
WEB3JSON_VERIFIER_URL_TESTNET=https://fdc-verifiers-testnet.flare.network/
COSTON2_DA_LAYER_URL="https://ctn2-data-availability.flare.network/"

# Compile all smart contracts
npx hardhat compile

import { run, web3 } from "hardhat";
import { StarWarsCharacterListV2 } from "../../typechain-types";

import {
    prepareAttestationRequestBase,
    submitAttestationRequest,
    retrieveDataAndProofBaseWithRetry,
} from "../utils/fdc";

const StarWarsCharacterListV2 = artifacts.require("StarWarsCharacterListV2");

const {
    ATTESTATION_PROVIDER_URL_TESTNET,
    VERIFIER_API_KEY_TESTNET,
    COSTON2_DA_LAYER_URL
} = process.env;

// yarn hardhat run scripts/fdcExample/Web2Json.ts --network coston2

// Request data
const apiUrl = "https://swapi.info/api/people/3";
const postProcessJq = `{name: .name, height: .height, mass: .mass, numberOfFilms: .films | length, uid: (.url | split("/") | .[-1] | tonumber)}`;
const httpMethod = "GET";
const headers = "{}";
const queryParams = "{}";
const body = "{}";
const abiSignature = `{"components": [{"internalType": "string", "name": "name", "type": "string"},{"internalType": "uint256", "name": "height", "type": "uint256"},{"internalType": "uint256", "name": "mass", "type": "uint256"},{"internalType": "uint256", "name": "numberOfFilms", "type": "uint256"},{"internalType": "uint256", "name": "uid", "type": "uint256"}],"name": "task","type": "tuple"}`;

const attestationTypeBase = "Web2Json";
const sourceIdBase = "PublicWeb2";
const verifierUrlBase = ATTESTATION_PROVIDER_URL_TESTNET;

async function prepareAttestationRequest(apiUrl: string, postProcessJq: string, abiSignature: string) {
    const requestBody = {
        url: apiUrl,
        httpMethod: httpMethod,
        headers: headers,
        queryParams: queryParams,
        body: body,
        postProcessJq: postProcessJq,
        abiSignature: abiSignature,
    };

    const url = `${verifierUrlBase}Web2Json/prepareRequest`;
    const apiKey = VERIFIER_API_KEY_TESTNET;

    return await prepareAttestationRequestBase(url, apiKey, attestationTypeBase, sourceIdBase, requestBody);
}

async function retrieveDataAndProof(abiEncodedRequest: string, roundId: number) {
    const url = `${COSTON2_DA_LAYER_URL}api/v1/fdc/proof-by-request-round-raw`;
    console.log("Url:", url, "n");
    return await retrieveDataAndProofBaseWithRetry(url, abiEncodedRequest, roundId);
}

async function deployAndVerifyContract() {
    const args: any[] = [];
    const characterList: StarWarsCharacterListV2Instance = await StarWarsCharacterListV2.new(...args);
    try {
        await run("verify:verify", {
            address: characterList.address,
            constructorArguments: args,
        });
    } catch (e: any) {
        console.log(e);
    }
    console.log("StarWarsCharacterListV2 deployed to", characterList.address, "\n");
    return characterList;
}

async function interactWithContract(characterList: StarWarsCharacterListV2Instance, proof: any) {
    console.log("Proof hex:", proof.response_hex, "\n");

    const IWeb2JsonVerification = await artifacts.require("IWeb2JsonVerification");
    const responseType = IWeb2JsonVerification._json.abi[0].inputs[0].components[1];
    console.log("Response type:", responseType, "\n");

    const decodedResponse = web3.eth.abi.decodeParameter(responseType, proof.response_hex);
    console.log("Decoded proof:", decodedResponse, "\n");
    const transaction = await characterList.addCharacter({
        merkleProof: proof.proof,
        data: decodedResponse,
    });
    console.log("Transaction:", transaction.tx, "\n");
    console.log("Star Wars Characters:\n", await characterList.getAllCharacters(), "\n");
}

async function main() {
    const data = await prepareAttestationRequest(apiUrl, postProcessJq, abiSignature);
    console.log("Data:", data, "\n");

    const abiEncodedRequest = data.abiEncodedRequest;
    const roundId = await submitAttestationRequest(abiEncodedRequest);

    const proof = await retrieveDataAndProof(abiEncodedRequest, roundId);

    const characterList: StarWarsCharacterListV2Instance = await deployAndVerifyContract();

    await interactWithContract(characterList, proof);
}

void main().then(() => {
    process.exit(0);
});

# Execute the complete Web2JSON workflow
npx hardhat run scripts/fdcExample/Web2Json.ts --network coston2

{
  "url": "Where to get the data (website address)",
  "httpMethod": "How to fetch it (GET, POST, etc.)", 
  "headers": "Any special headers needed",
  "queryParams": "URL parameters to include",
  "body": "Data to send for POST requests",
  "postProcessJq": "Which fields to extract and how to format them",
  "abiSignature": "How to package the data for blockchain use"
}

//  WHERE to get data
const apiUrl = "https://swapi.info/api/people/3";
// ↑ "Go to Star Wars API and get character #3 (R2-D2)"

//  WHAT data to extract and HOW to format it
const postProcessJq = `{
  name: .name,                    // "Get the character's name"
  height: .height,                // "Get their height as a number"  
  mass: .mass,                    // "Get their weight as a number"
  numberOfFilms: .films | length, // "Count how many films they appear in"
  uid: (.url | split("/") | .[-1] | tonumber) // "Extract their ID number from the URL"
}`;

//  HOW to package for blockchain
const abiSignature = `{
  "components": [
    {"internalType": "string", "name": "name", "type": "string"},
    {"internalType": "uint256", "name": "height", "type": "uint256"},
    {"internalType": "uint256", "name": "mass", "type": "uint256"}, 
    {"internalType": "uint256", "name": "numberOfFilms", "type": "uint256"},
    {"internalType": "uint256", "name": "uid", "type": "uint256"}
  ],
  "name": "task",
  "type": "tuple"
}`;
// ↑ "Package the data in this exact structure for the blockchain"

function toHex(data: string) {
  var result = "";
  
  // Go through each letter one by one
  for (var i = 0; i < data.length; i++) {
    // Convert: W → 57, e → 65, b → 62, etc.
    result += data.charCodeAt(i).toString(16);
  }
  
  // Make sure it's exactly 64 characters long by adding zeros
  return result.padEnd(64, "0");
}

function toUtf8HexString(data: string) {
  // Just add "0x" to the beginning
  return "0x" + toHex(data);
}

async function prepareAttestationRequestBase(
  url: string,                    // Where to send the request
  apiKey: string,                 // Your Flare API key (like restaurant membership)
  attestationTypeBase: string,    // "Web2Json" - type of data you want
  sourceIdBase: string,           // "PublicWeb2" - where data comes from  
  requestBody: any,               // Your detailed order from Step 1
) {
  console.log("Url:", url, "\n");
  
  // Convert text to hex format that blockchain understands
  const attestationType = toUtf8HexString(attestationTypeBase);
  const sourceId = toUtf8HexString(sourceIdBase);

  // Package everything together
  const request = {
    attestationType: attestationType,
    sourceId: sourceId,
    requestBody: requestBody,     // Your Star Wars API instructions
  };
  console.log("Prepared request:\n", request, "\n");

  // Send to Flare's verifier
  const response = await fetch(url, {
    method: "POST",
    headers: {
      "X-API-KEY": apiKey,        // Your API key for authentication
      "Content-Type": "application/json",
    },
    body: JSON.stringify(request), // Your order in JSON format
  });
  
  // Check if request was accepted
  if (response.status != 200) {
    throw new Error(
      `Response status is not OK, status ${response.status} ${response.statusText}\n`,
    );
  }
  console.log("Response status is OK\n");

  // Get your "order number" (ABI encoded request)
  return await response.json();
}

async function prepareAttestationRequest(
  apiUrl: string,           // Star Wars API URL
  postProcessJq: string,    // Which fields to extract
  abiSignature: string,     // How to format the data
) {
  // Package your specific Web2JSON order
  const requestBody = {
    url: apiUrl,
    httpMethod: "GET",
    headers: "{}",
    queryParams: "{}", 
    body: "{}",
    postProcessJq: postProcessJq,
    abiSignature: abiSignature,
  };

  // Send to the right "counter" (Web2Json endpoint)
  const url = `${verifierUrlBase}Web2Json/prepareRequest`;
  const apiKey = VERIFIER_API_KEY_TESTNET;

  // Let the cashier handle the rest
  return await prepareAttestationRequestBase(
    url,
    apiKey,
    "Web2Json",     // Always Web2Json for this type of data
    "PublicWeb2",   // Always PublicWeb2 for public APIs
    requestBody,
  );
}

contract Helpers {
    // These are like different "buttons" on your remote control:
    
    function getFdcHub() public view returns (IFdcHub) {
        return ContractRegistry.getFdcHub();           // "Submit request" button
    }

    function getFdcRequestFeeConfigurations() public view returns (IFdcRequestFeeConfigurations) {
        return ContractRegistry.getFdcRequestFeeConfigurations(); // "Check price" button
    }

    function getFlareSystemsManager() public view returns (IFlareSystemsManager) {
        return ContractRegistry.getFlareSystemsManager();         // "Check time" button
    }

    function getRelay() public view returns (IRelay) {
        return ContractRegistry.getRelay();                       // "Verify completion" button
    }
}

async function submitAttestationRequest(abiEncodedRequest: string) {
  // Get the "submit request" button from our remote control
  const fdcHub = await getFdcHub();

  // Check how much this request costs
  const requestFee = await getFdcRequestFee(abiEncodedRequest);

  // Submit to blockchain and pay the fee
  const transaction = await fdcHub.requestAttestation(abiEncodedRequest, {
    value: requestFee,  // Pay the required fee
  });
  console.log("Submitted request:", transaction.tx, "\n");

  // Find out which "voting round" we're in
  const roundId = await calculateRoundId(transaction);
  console.log(
    `Check round progress at: https://${hre.network.name}-systems-explorer.flare.rocks/voting-epoch/${roundId}?tab=fdc\n`,
  );
  return roundId;  // This tells us how long to wait
}

async function getFdcRequestFee(abiEncodedRequest: string) {
  // Use the "check price" button from our remote control
  const helpers = await getHelpers();
  const feeConfigAddress = await helpers.getFdcRequestFeeConfigurations();
  const feeConfig = await FdcRequestFeeConfigurations.at(feeConfigAddress);
  
  // Ask "How much does this request cost?"
  return await feeConfig.getRequestFee(abiEncodedRequest);
}

async function calculateRoundId(transaction: any) {
  // Check when our transaction happened
  const blockNumber = transaction.receipt.blockNumber;
  const block = await ethers.provider.getBlock(blockNumber);
  const blockTimestamp = BigInt(block!.timestamp);

  // Use the "check time" button from our remote control
  const flareSystemsManager = await getFlareSystemsManager();
  const firstRoundStart = BigInt(await flareSystemsManager.firstVotingRoundStartTs());
  const roundDuration = BigInt(await flareSystemsManager.votingEpochDurationSeconds());

  // Calculate: (Current time - First round time) ÷ 90 seconds
  const roundId = Number(
    (blockTimestamp - firstRoundStart) / roundDuration
  );
  
  console.log("Calculated round id:", roundId, "\n");
  return roundId;  // This is like getting your "batch number"
}

// What we store in our collection
struct StarWarsCharacter {
    string name;           // Character name (R2-D2)
    uint256 numberOfMovies; // How many films they appeared in
    uint256 apiUid;        // Unique ID from Star Wars API  
    uint256 bmi;           // Calculated BMI (Body Mass Index)
}

// How data arrives from Flare (temporary package)
struct DataTransportObject {
    string name;           // Name from API
    uint256 height;        // Height in cm
    uint256 mass;          // Weight in kg
    uint256 numberOfMovies; // Film count
    uint256 apiUid;        // API ID number
}

contract StarWarsCharacterList {
    // Our collection storage
    mapping(uint256 => StarWarsCharacter) public characters;  // Store by ID
    uint256[] public characterIds;                           // List of all IDs

    // STEP 1: Verify the data is authentic
    function isWeb2JsonProofValid(IWeb2Json.Proof calldata _proof) 
        private view returns (bool) 
    {
        // Ask Flare: "Is this data legit?"
        return ContractRegistry.getFdcVerification().verifyJsonApi(_proof);
    }

    // STEP 2: Add a new character to our collection
    function addCharacter(IWeb2Json.Proof calldata data) public {
        // First, verify the proof is valid
        require(isWeb2JsonProofValid(data), "Invalid proof");
        // ↑ If proof is fake, STOP everything!

        // STEP 3: Unpack the verified data
        DataTransportObject memory dto = abi.decode(
            data.data.responseBody.abi_encoded_data,
            (DataTransportObject)
        );
        // ↑ This extracts: name, height, mass, film count, ID

        // STEP 4: Check if we already have this character
        require(characters[dto.apiUid].apiUid == 0, "Character already exists");

        // STEP 5: Calculate BMI from verified height & mass
        uint256 bmi = (dto.mass * 100 * 100) / (dto.height * dto.height);

        // STEP 6: Create our character record
        StarWarsCharacter memory character = StarWarsCharacter({
            name: dto.name,
            numberOfMovies: dto.numberOfFilms,
            apiUid: dto.apiUid,
            bmi: bmi  // Our calculated value!
        });

        // STEP 7: Store in our collection
        characters[dto.apiUid] = character;
        characterIds.push(dto.apiUid);
    }

    // STEP 8: View all characters in our collection
    function getAllCharacters() public view returns (StarWarsCharacter[] memory) {
        StarWarsCharacter[] memory result = new StarWarsCharacter[](characterIds.length);
        
        // Get each character by their ID
        for (uint256 i = 0; i < characterIds.length; i++) {
            result[i] = characters[characterIds[i]];
        }
        
        return result;  // Returns array of all characters
    }
}

async function deployAndVerifyContract() {
  const args: any[] = [];
  
  // Deploy our Star Wars collection contract
  const characterList = await StarWarsCharacterList.new(...args);
  
  try {
    // Verify contract on block explorer (optional)
    await run("verify:verify", {
      address: characterList.address,
      constructorArguments: args,
    });
  } catch (e: any) {
    console.log(e);  // If verification fails, just continue
  }
  
  console.log("StarWarsCharacterList deployed to", characterList.address, "\n");
  return characterList;
}

async function interactWithContract(
  characterList: StarWarsCharacterListInstance,
  proof: any,
) {
  console.log("Proof hex:", proof.response_hex, "\n");

  //  STEP 1: Understand the data structure from Flare
  const IWeb2JsonVerification = await artifacts.require("IWeb2JsonVerification");
  const responseType = IWeb2JsonVerification._json.abi[0].inputs[0].components[1];
  console.log("Response type:", responseType, "\n");

  // STEP 2: Unpack the verified data
  const decodedResponse = web3.eth.abi.decodeParameter(responseType, proof.response_hex);
  console.log("Decoded proof:", decodedResponse, "\n");
  
  //  STEP 3: Add R2-D2 to our collection
  const transaction = await characterList.addCharacter({
    merkleProof: proof.proof,    // The crypto-proof from Flare
    data: decodedResponse,       // The actual R2-D2 data
  });
  
  console.log("Transaction:", transaction.tx, "\n");
  
  //  STEP 4: Display our complete collection
  console.log("Star Wars Characters:\n", await characterList.getAllCharacters(), "\n");
}

npx hardhat run scripts/fdcExample/Web2Json.ts --network coston2

// Fetch Bitcoin price from CoinGecko
const apiUrl = "https://api.coingecko.com/api/v3/simple/price?ids=bitcoin&vs_currencies=usd";
const postProcessJq = `{ price: .bitcoin.usd }`;
const abiSignature = `{"components":[{"internalType":"uint256","name":"price","type":"uint256"}],"name":"task","type":"tuple"}`;

// Your contract can now use verified Bitcoin price for DeFi applications!

// Fetch current temperature for New York
const apiUrl = "https://api.open-meteo.com/v1/forecast?latitude=40.71&longitude=-74.01&current=temperature_2m";
const postProcessJq = `{ temperature: .current.temperature_2m }`;
const abiSignature = `{"components":[{"internalType":"uint256","name":"temperature","type":"uint256"}],"name":"task","type":"tuple"}`;

// Create weather-based insurance or event contracts!

// Fetch football match results
const apiUrl = "https://api.football-data.org/v4/matches";
const postProcessJq = `{ totalMatches: .resultSet.count }`;
const abiSignature = `{"components":[{"internalType":"uint256","name":"totalMatches","type":"uint256"}],"name":"task","type":"tuple"}`;

// Build prediction markets or fantasy sports!