From 39eab2f200274201117cd75ef44c6de0ccfc73ea Mon Sep 17 00:00:00 2001 From: santiagodevrel Date: Fri, 26 Jul 2024 22:01:23 +0300 Subject: [PATCH 1/6] updated readme --- README.md | 219 +++++++++++++++++++++++------------------------------- 1 file changed, 93 insertions(+), 126 deletions(-) diff --git a/README.md b/README.md index 2ac9df0..54e4c1a 100644 --- a/README.md +++ b/README.md @@ -7,186 +7,153 @@ This is a [web3.js](https://github.com/web3/web3.js) `4.x` plugin for interactin ## Prerequisites -- :gear: [NodeJS](https://nodejs.org/) (LTS/Fermium) -- :toolbox: [Yarn](https://yarnpkg.com/) +- :gear: [NodeJS](https://nodejs.org/) (LTS/Fermium) +- :toolbox: [Yarn](https://yarnpkg.com/) ## Installation ```bash -yarn add @ora-io/web3-plugin-ora +yarn add web3 ``` +Or - -## Using this plugin - -### Installing Version `4.x` of `web3` - -When adding the `web3` package to your project, make sure to use version `4.x`: - -- `npm i -S web3@4.0.3` -- `yarn add web3@4.0.3` - -> **_NOTE_** -> If 4.x was already released, you are good to just use `web3` without appending anything to it. - -To verify you have the correct `web3` version installed, after adding the package to your project (the above commands), look at the versions listed in your project's `package.json` under the `dependencies` section, it should contain version 4.x similar to: - -```json -"dependencies": { - "web3": "4.0.3" -} +```bash +npm i web3 ``` -### Configure .env file - -In order to interact with the blockchain through web3js plugin you need to setup environment variables. To do that, copy `.env.example` into `.env` and add values for `PRIVATE_KEY` and `RPC_URL`. - -### Registering the Plugin with a web3.js Instance - -After importing `ORAPlugin` from `@ora-io/web3-plugin-ora` and `Web3` from `web3`, register an instance of `ORAPlugin` with an instance of `Web3` like so: - -```typescript -import { Web3 } from 'web3'; -import dotenv from 'dotenv'; -import {Models, ORAPlugin, PromptAddresses} from '@ora-io/web3-plugin-ora'; - -dotenv.config(); +```bash +yarn add @ora-io/web3-plugin-ora +``` -const web3 = new Web3(process.env.RPC_URL); -const oraPlugin = new ORAPlugin(PromptAddresses.SEPOLIA); +Or -web3.registerPlugin(oraPlugin); +```bash +npm i @ora-io/web3-plugin-ora ``` +## Getting started +To interact with ORA's web3js plugin you need to follow next steps: -More information about registering web3.js plugins can be found [here](https://docs.web3js.org/docs/guides/web3_plugin_guide/plugin_users#registering-the-plugin). +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`) -### Plugin Methods +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](https://docs.ora.io/doc/oao-onchain-ai-oracle/develop-guide/tutorials/interaction-with-oao-tutorial). -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. +In this example we will interact with the ORA contract deployed in the Sepolia network. -#### `estimateFee` +:::Info +[here](https://github.com/ora-io/web3.js-plugin-ora/blob/master/src/types.ts) you can find other available networks +::: -```typescript -public async estimateFee( - modelId: Models -) -``` -`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. +```ts +import { Web3 } from "web3"; +import { Models, ORAPlugin, PromptAddresses } from "@ora-io/web3-plugin-ora"; -**Input:** -- `modelId` - specifies AI model for fee estimation +// Initialize RPC endpoint (in this case with Sepolia Testnet) +const web3 = new Web3("https://1rpc.io/sepolia"); -#### `calculateAIResult` +// Step 1: Register the ORAPlugin to the web3.js context pointint to the Sepolia Testnet network +web3.registerPlugin(new ORAPlugin(PromptAddresses.SEPOLIA)); -```typescript -public async calculateAIResult( - from: string, - modelId: Models, - prompt: string, - estimatedFee: string, -) -``` +// Step 2: Add private key to initialize a wallet +const wallet = web3.eth.accounts.wallet.add("PRIVATE_KEY"); // Make sure you have funds -`calculateAIResult` interacts with Onchain AI Oracle (OAO), requesting AI inference. +async function main() { + const PROMPT = "Generate image of an eagle that explores the world"; -**Input:** -- `from` - specifies the sender of the transaction (connected wallet address) -- `modelId` - id of the AI model that should be called -- `prompt` - custom prompt for inference request -- `estimatedFee` - result of `estimateFee` method + // 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 -#### `getAIResult` + // Step 5: Fetch the result + const result = await web3.ora.getAIResult(Models.STABLE_DIFFUSION, PROMPT); + console.log("Inference result: ", result); + //→ Inference result: QmQkxg31E9b8mCMAW8j2LYB46LM8ghExbXrQHob26WLos1 +} -```typescript -public async getAIResult( - modelId: Models, - prompt: string -) +main(); ``` -`getAIResult` is used to query inference result for the specific prompt and modelId. +In this example we interacted with `STABLE_DIFFUSION` model, hence the result is a [CID](https://pinata.cloud/blog/what-is-an-ipfs-cid/#:~:text=The%20CID%20is%20a%20unique,%2C%20such%20as%20SHA%2D256.) of an image stored on ipfs. You can check generated image here: https://ipfs.io/ipfs/QmQkxg31E9b8mCMAW8j2LYB46LM8ghExbXrQHob26WLos1 -**Inputs:** - -- `modelId` - speficies the AI model which will return inference results -- `prompt` - user prompt string for the inference call - -Under the hood, this method is calling the `getAIResult` on the Prompt contract for the specified model and prompt. +You can experiment by changing modelId and prompt to get different inferences from all supported models. -## Getting started guide +## Introduction to Onchain AI Oracle (OAO) -### 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](https://docs.ora.io/doc/oao-onchain-ai-oracle/reference) - To understand why verifiability matters, check out this [page](https://docs.ora.io/doc/oao-onchain-ai-oracle/introduction/why-verifiability-matters) - To explore existing AI powered dapps and use cases visit [awesome-ora](https://github.com/ora-io/awesome-ora) ![image representing the flow of interaction with OAO](oao_image.png) -### Sample code to interact with OAO -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](https://docs.ora.io/doc/oao-onchain-ai-oracle/develop-guide/tutorials/interaction-with-oao-tutorial). +## Plugin Methods -```typescript -import { Web3 } from 'web3'; -import dotenv from 'dotenv'; -import {Models, ORAPlugin, PromptAddresses} from '@ora-io/web3-plugin-ora'; +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. -dotenv.config(); +### `estimateFee` -const web3 = new Web3(process.env.RPC_URL); +`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. -const oraPlugin = new ORAPlugin(PromptAddresses.SEPOLIA); -web3.registerPlugin(oraPlugin); +```typescript +/** + * @param modelId specifies AI model for fee estimation + */ -const acc = web3.eth.accounts.privateKeyToAccount(process.env.PRIVATE_KEY ? process.env.PRIVATE_KEY : "") -web3.eth.accounts.wallet.add(acc); +web3.ora.estimateFee(modelId: Models) +// => Returns BigInt +``` -const PROMPT = "Generate image of an alien that explores the world" +### `calculateAIResult` -const estimatedFee = await web3.ora.estimateFee(Models.STABLE_DIFFUSION); -console.log("Estimated fee: ", estimatedFee) -await web3.ora.calculateAIResult(acc.address, Models.STABLE_DIFFUSION, PROMPT, Number(estimatedFee).toString()) +`calculateAIResult` interacts with Onchain AI Oracle (OAO), requesting AI inference. -setTimeout(async () => { - const inferenceResult = await web3.ora.getAIResult(Models.STABLE_DIFFUSION, PROMPT); - console.log("Inference result: ", inferenceResult) -}, 20000); +```typescript +/** + * @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 ``` -To interact with ORA's web3js plugin you need to follow next steps: -1. register ORA plugin to web3js -2. add wallet to web3js 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`) - -In this example we interacted with StableDiffusion model, hence the result is a CID of an image stored on ipfs. You can check generated image here: https://ipfs.io/ipfs/QmbaJs2fcbr4dfD5Mf8pJu7xvheGbQEksRtVN4ryEL8THp +### `getAIResult` -You can experiment by changing modelId and prompt to get different inferences from all supported models. +`getAIResult` is used to query inference result for the specific prompt and modelId. -## Found an issue or have a question or suggestion +```typescript +/** + * @param modelId speficies the AI model which will return inference results + * @param prompt user prompt string for the inference call + */ -- If you found an issue or have a question or suggestion [submit an issue](https://github.com/ora-io/web3.js-plugin-ora/issues) or join us on [Discord](https://discord.gg/fg5ygkgy) +const result = await web3.ora.getAIResult(Models.STABLE_DIFFUSION, PROMPT); +// => Returns String with the ORA AI result +``` -## Run the tests +Under the hood, this method is calling the `getAIResult` function on the `Prompt` contract for the specified model and prompt. -1. Clone the repo -2. Run `yarn` to install dependencies - - If you receive the following warning, please remove the file `package-lock.json` and make sure to run `yarn` to install dependencies instead of `npm i`: +## Useful links -```console -warning package-lock.json found. Your project contains lock files generated by tools other than Yarn. It is advised not to mix package managers in order to avoid resolution inconsistencies caused by unsynchronized lock files. To clear this warning, remove package-lock.json. -``` +- [web3.js Documentation](https://docs.web3js.org/) +- [ORA Documentation](https://docs.ora.io/doc) +- [awesome-ora](https://github.com/ora-io/awesome-ora) -3. Run the tests: - - `yarn test`: Runs test against the network specified by RPC_URL - -## Useful links +## Found an issue or have a question or suggestion -- [web3.js Documentation](https://docs.web3js.org/) -- [ORA Documentation](https://docs.ora.io/doc) -- [awesome-ora](https://github.com/ora-io/awesome-ora) +- If you found an issue or have a question or suggestion [submit an issue](https://github.com/ora-io/web3.js-plugin-ora/issues) or join us on [Discord](https://discord.gg/fg5ygkgy) From 5ea9f1d1b800fd3ae4e2e2a4095fa4f81787ee11 Mon Sep 17 00:00:00 2001 From: santiagodevrel Date: Fri, 26 Jul 2024 22:05:06 +0300 Subject: [PATCH 2/6] updated npm,yarn and added a note --- README.md | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 54e4c1a..1066859 100644 --- a/README.md +++ b/README.md @@ -12,24 +12,22 @@ This is a [web3.js](https://github.com/web3/web3.js) `4.x` plugin for interactin ## Installation -```bash -yarn add web3 -``` - -Or - ```bash npm i web3 ``` ```bash -yarn add @ora-io/web3-plugin-ora +npm i @ora-io/web3-plugin-ora ``` Or ```bash -npm i @ora-io/web3-plugin-ora +yarn add web3 +``` + +```bash +yarn add @ora-io/web3-plugin-ora ``` ## Getting started @@ -46,9 +44,8 @@ This section will help you get started with utilizing OAO in your smart contract In this example we will interact with the ORA contract deployed in the Sepolia network. -:::Info -[here](https://github.com/ora-io/web3.js-plugin-ora/blob/master/src/types.ts) you can find other available networks -::: +> **_NOTE_** +> [here](https://github.com/ora-io/web3.js-plugin-ora/blob/master/src/types.ts) you can find other available networks ```ts import { Web3 } from "web3"; From 4ed666b876c52de08942d305f859a8db26bc03d4 Mon Sep 17 00:00:00 2001 From: santiagodevrel Date: Fri, 26 Jul 2024 22:08:47 +0300 Subject: [PATCH 3/6] updated noted --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index 1066859..36a7df2 100644 --- a/README.md +++ b/README.md @@ -44,7 +44,6 @@ This section will help you get started with utilizing OAO in your smart contract In this example we will interact with the ORA contract deployed in the Sepolia network. -> **_NOTE_** > [here](https://github.com/ora-io/web3.js-plugin-ora/blob/master/src/types.ts) you can find other available networks ```ts From 31fbba61762914526c39add23b318935d38c40ee Mon Sep 17 00:00:00 2001 From: santiagodevrel Date: Fri, 26 Jul 2024 22:10:22 +0300 Subject: [PATCH 4/6] fixed typos --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 36a7df2..670dda7 100644 --- a/README.md +++ b/README.md @@ -108,7 +108,7 @@ ORAPlugin supports method for getting AI inference results from all supported ch * @param modelId specifies AI model for fee estimation */ -web3.ora.estimateFee(modelId: Models) +await web3.ora.estimateFee(Models.STABLE_DIFFUSION || Models.LLAMA2 || Models.OPENLM); // => Returns BigInt ``` @@ -138,7 +138,7 @@ await web3.ora.calculateAIResult(wallet[0].address, Models.STABLE_DIFFUSION, PRO * @param prompt user prompt string for the inference call */ -const result = await web3.ora.getAIResult(Models.STABLE_DIFFUSION, PROMPT); +await web3.ora.getAIResult(Models.STABLE_DIFFUSION, PROMPT); // => Returns String with the ORA AI result ``` From cb950ef25d4668404fd937cd73212792373e7ce6 Mon Sep 17 00:00:00 2001 From: hadzija7 <48260177+hadzija7@users.noreply.github.com> Date: Mon, 29 Jul 2024 11:26:31 +0200 Subject: [PATCH 5/6] Update README.md - Added timeout (30s), to give oracle time to return inference result. - Added note for PRIVATE_KEY exposure --- README.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 670dda7..216ef4c 100644 --- a/README.md +++ b/README.md @@ -53,10 +53,10 @@ 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 pointint to the Sepolia Testnet network +// 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 +// 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() { @@ -71,11 +71,14 @@ async function main() { const tx = await web3.ora.calculateAIResult(wallet[0].address, Models.STABLE_DIFFUSION, PROMPT, estimatedFee); //console.log(tx); //→ Transaction receipt - - // Step 5: Fetch the result - const result = await web3.ora.getAIResult(Models.STABLE_DIFFUSION, PROMPT); - console.log("Inference result: ", result); - //→ Inference result: QmQkxg31E9b8mCMAW8j2LYB46LM8ghExbXrQHob26WLos1 + console.log("Oracle is generating result...") + + // Step 5: Fetch the result (note: we are waiting 25s 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(); From 579d258941223070460981ad71efd71917db175d Mon Sep 17 00:00:00 2001 From: hadzija7 <48260177+hadzija7@users.noreply.github.com> Date: Mon, 29 Jul 2024 11:30:39 +0200 Subject: [PATCH 6/6] Update README.md changed timeout duration --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 216ef4c..8f6c285 100644 --- a/README.md +++ b/README.md @@ -73,7 +73,7 @@ async function main() { //→ Transaction receipt console.log("Oracle is generating result...") - // Step 5: Fetch the result (note: we are waiting 25s before fetching, to be sure that oracle returned the 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);