ora-io / web3.js-plugin-ora

Web3.js ORA Plugin

This is a web3.js 4.x plugin for interacting with ORA Ethereum contracts.

Prerequisites

• ⚙️ NodeJS (LTS/Fermium)
• 🧰 Yarn

Installation

npm i web3

npm i @ora-io/web3-plugin-ora

Or

yarn add web3

yarn add @ora-io/web3-plugin-ora

Getting started

To interact with ORA's web3js plugin you need to follow next steps:

1. Register ORA plugin to web3.js context
2. Add wallet to web3.js context, in order to sign blockchain transactions
3. Estimate fee for the OAO callback (estimateFee)
4. Initiate inference request (calculateAIResult)
5. Check the inference result (getAIResult)

This section will help you get started with utilizing OAO in your smart contracts. In depth tutorial on how to interact with ORA's Onchain AI Oracle can be found here.

In this example we will interact with the ORA contract deployed in the Sepolia network.

here you can find other available networks

import { Web3 } from "web3";
import { Models, ORAPlugin, PromptAddresses } from "@ora-io/web3-plugin-ora";

// Initialize RPC endpoint (in this case with Sepolia Testnet)
const web3 = new Web3("https://1rpc.io/sepolia");

// Step 1: Register the ORAPlugin to the web3.js context pointing to the Sepolia Testnet network
web3.registerPlugin(new ORAPlugin(PromptAddresses.SEPOLIA));

// Step 2: Add private key to initialize a wallet (note: NEVER PUSH/SHOW your private key)
const wallet = web3.eth.accounts.wallet.add("PRIVATE_KEY"); // Make sure you have funds

async function main() {
  const PROMPT = "Generate image of an eagle that explores the world";

  // Step 3: Estimate fee
  const estimatedFee = await web3.ora.estimateFee(Models.STABLE_DIFFUSION);
  console.log("Estimated fee: ", estimatedFee);
  //→ Estimated fee:  14842518431500000n

  // Step 4: Initiate inference request
  const tx = await web3.ora.calculateAIResult(wallet[0].address, Models.STABLE_DIFFUSION, PROMPT, estimatedFee);
  //console.log(tx);
  //→ Transaction receipt
  console.log("Oracle is generating result...")

  // Step 5: Fetch the result (note: we are waiting 30s before fetching, to be sure that oracle returned the result)
  setTimeout(async () => {
      const result = await web3.ora.getAIResult(Models.STABLE_DIFFUSION, PROMPT);
      console.log("Inference result: ", result);
      //→ Inference result:  QmQkxg31E9b8mCMAW8j2LYB46LM8ghExbXrQHob26WLos1
  }, 30000);
}

main();

In this example we interacted with STABLE_DIFFUSION model, hence the result is a CID of an image stored on ipfs. You can check generated image here: https://ipfs.io/ipfs/QmQkxg31E9b8mCMAW8j2LYB46LM8ghExbXrQHob26WLos1

You can experiment by changing modelId and prompt to get different inferences from all supported models.

Introduction to Onchain AI Oracle (OAO)

Onchain AI Oracle (OAO) is the ORA's verifiable and decentralized AI oracle. Smart contracts can request an AI inference from OAO, and it will return a verifiable result. Different AI models are integrated into the oracle nodes. When interacting with OAO, users need to specify id of the model they are willing to interact with. The result will vary depending on the model used (eg. Stable-Diffusion generates image, while Llama3 generates text result).

• You can check all supported models in the documentation
• To understand why verifiability matters, check out this page
• To explore existing AI powered dapps and use cases visit awesome-ora

Plugin Methods

ORAPlugin supports method for getting AI inference results from all supported chains. When interacting with the plugin, users need to specify which chain to interact with.

estimateFee

estimateFee method is used to determine amount of wei necessary for oracle to execute callback and return inference result. Estimated fee is passed as a value for calculateAIResult function call.

/**
 * @param modelId specifies AI model for fee estimation
 */

await web3.ora.estimateFee(Models.STABLE_DIFFUSION || Models.LLAMA2 || Models.OPENLM);
// => Returns BigInt

calculateAIResult

calculateAIResult interacts with Onchain AI Oracle (OAO), requesting AI inference.

/**
 * @param from specifies the sender of the transaction (connected wallet address)
 * @param modelId id of the AI model that should be called
 * @param prompt custom prompt for inference request
 * @param estimatedFee result of `estimateFee` method
 */

await web3.ora.calculateAIResult(wallet[0].address, Models.STABLE_DIFFUSION, PROMPT, estimatedFee);
// => Returns Transaction receipt

getAIResult

getAIResult is used to query inference result for the specific prompt and modelId.

/**
 * @param modelId speficies the AI model which will return inference results
 * @param prompt user prompt string for the inference call
 */

await web3.ora.getAIResult(Models.STABLE_DIFFUSION, PROMPT);
// => Returns String with the ORA AI result

Under the hood, this method is calling the getAIResult function on the Prompt contract for the specified model and prompt.

Useful links

• web3.js Documentation
• ORA Documentation
• awesome-ora

Found an issue or have a question or suggestion

• If you found an issue or have a question or suggestion submit an issue or join us on Discord