/phat-contract-starter-kit

Send data from any API to your smart contract with Javascript

Primary LanguageTypeScriptGNU General Public License v3.0GPL-3.0

⚒️ The Phat Contract Starter Kit

Note on Terminology

Phat Contract will also be referred to as the Phala Oracle in this README.

🔎 Overview

The Phat Contract Starter Kit is your one-stop solution to connect any API to your smart contract. It offers wide-ranging support for all EVM-compatible blockchains, including but not limited to Ethereum, Polygon, Arbitrum, Avalanche, Binance Smart Chain, Optimism, and zkSync.

This starter kit empowers you to initiate the data request from the smart contract side. The request is then seamlessly sent to your script for processing. You have the liberty to call any APIs to fulfill the request and define the response data structure that will be replied to your smart contract.

🏃 Quick Start

To kickstart your journey with the Phat Contract Starter Kit, you have 2 options:

  1. Create a template from the phat-contract-starter-kit template repo. Click on the "Use this template" button in the top right corner of the webpage. Then skip the npx @phala/fn@latest init example step.
  2. Install the @phala/fn CLI tool. You can do this using your node package manager (npm) or use node package execute (npx). For the purpose of this tutorial, we will be using npx.

(Option 2) Once you have the CLI tool installed, you can create your first Phala Oracle template with the following command.

# Skip this step if chose option 1 or cloned this repo
npx @phala/fn@latest init example
🚨 Note 🚨

When selecting your template, elect phat-contract-starter-kit.

npx @phala/fn@latest init example
? Please select one of the templates for your "example" project: (Use arrow keys)
❯ phat-contract-starter-kit. The Phat Contract Starter Kit 
  lensapi-oracle-consumer-contract. Polygon Consumer Contract for LensAPI Oracle

🛑 Not so fast! What is it exactly that we are building? 🛑

What are we building?

The artifact we are compiling is a JavaScript file, serving as the Phat Contract Oracle's tailored logic. This script is designed to respond to requests initiated from the Consumer Contract. The diagram provided above offers a visual representation of this request-response interaction.

Why is it important?

In the context of the off-chain environment, on-chain Smart Contracts are inherently limited. Their functionality is confined to the information available to them within the on-chain ecosystem. This limitation underscores the critical need for a secure off-chain oracle, such as the Phat Contract. This oracle is capable of fetching and transforming data, thereby enhancing the intelligence and awareness of Smart Contracts about on-chain activities. This is a pivotal step towards bridging the gap between the on-chain and off-chain worlds, making Smart Contracts not just smart, but also informed.

After creating a Phala Oracle template, cd into the new project and install the package dependencies. You can do this with the following command:

yarn install

Now, build the default Phala Oracle function with this command:

yarn build-function

To simulate the expected result locally, run the Phala Oracle function now with this command:

yarn run-function -a 0x0000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000043078303100000000000000000000000000000000000000000000000000000000 https://api-mumbai.lens.dev

What are the ingredients for the yarn run-function command?

Our Phat Contract script, now fully constructed, is ready for a trial run. This simulation mirrors the live script's operation when deployed on the Phala Network.

The command's first parameter is a HexString, representing a tuple of types [uintCoder, bytesCoder]. This serves as the entry function. The second parameter is a string, embodying the configurable secrets fed into the main function.

The Coders.decode function deciphers these parameters, yielding the decoded requestId and encodedReqStr. These decoded elements then become the raw material for the rest of the custom logic within the script.

export default function main(request: HexString, secrets: string): HexString {
  console.log(`handle req: ${request}`);
  let requestId, encodedReqStr;
  try {
    [requestId, encodedReqStr] = Coders.decode([uintCoder, bytesCoder], request);
  } catch (error) {
    console.info("Malformed request received");
  }
// ...
}
How the query looks under the hood
  • HTTP Endpoint: https://api-mumbai.lens.dev
  • Profile ID: 0x01
  • Expected Graphql Query: 
    query Profile {
  profile(request: { profileId: "0x01" }) {
    stats {
        totalFollowers
        totalFollowing
        totalPosts
        totalComments
        totalMirrors
        totalPublications
        totalCollects
    }
  }
}
  • Expected Output: 
    {
  "data": {
    "profile": {
      "stats": {
        "totalFollowers": 3361,
        "totalFollowing": 0,
        "totalPosts": 3,
        "totalComments": 0,
        "totalMirrors": 0,
        "totalPublications": 3,
        "totalCollects": 1597
      }
    }
  }
}

Finally, run the local end-to-end tests with this command. Here we will simulate locally the interaction between the Phat Contract and the Consumer Contract with hardhat.

yarn hardhat test

🥳 Congratulations!

You have successfully completed the quick start. For the next steps, you will learn how to deploy your Phala Oracle and connect to the consumer contract for the EVM testnet chain to start testing the request-response model live.

For a deeper dive into the details, click here, or continue reading to learn about the valuable features the Phala Oracle can offer to your on-chain consumer contract.

🪄 Features and Benefits

  • Wide support for all mainstream blockchains
  • Verifiable and decentralized: every Oracle is running on decentralized infrastructure that require no operations and can be easily verified
  • Support private data: your Oracle state is protected by cryptography and hardware
  • No extra cost: the only cost is the gas fee of response data which is sent as a transaction
  • High frequency: the request is synced to Oracle within one minute, and the latency of response is only limited by blockchain’s block interval

🏗️ Use cases & Examples

You could use the Oracle to:

📚 Resources