Skip to content

Updated README guide #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Jul 29, 2024
Merged

Updated README guide #1

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
39eab2f
updated readme
Jul 26, 2024
5ea9f1d
updated npm,yarn and added a note
Jul 26, 2024
4ed666b
updated noted
Jul 26, 2024
31fbba6
fixed typos
Jul 26, 2024
cb950ef
Update README.md
hadzija7 Jul 29, 2024
579d258
Update README.md
hadzija7 Jul 29, 2024
2bbac51
Merge pull request #1 from hadzija7/master
Jul 29, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
220 changes: 93 additions & 127 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,186 +7,152 @@ 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
npm i web3
```



## 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 [email protected]`
- `yarn add [email protected]`

> **_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 @ora-io/web3-plugin-ora
```

### 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:
Or

```typescript
import { Web3 } from 'web3';
import dotenv from 'dotenv';
import {Models, ORAPlugin, PromptAddresses} from '@ora-io/web3-plugin-ora';

dotenv.config();

const web3 = new Web3(process.env.RPC_URL);
const oraPlugin = new ORAPlugin(PromptAddresses.SEPOLIA);
```bash
yarn add web3
```

web3.registerPlugin(oraPlugin);
```bash
yarn add @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`
> [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 pointing 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 (note: NEVER PUSH/SHOW your private key)
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
console.log("Oracle is generating result...")

#### `getAIResult`
// 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);
}

```typescript
public async getAIResult(
modelId: Models,
prompt: string
)
main();
```

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

**Inputs:**

- `modelId` - speficies the AI model which will return inference results
- `prompt` - user prompt string for the inference call
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

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);
await web3.ora.estimateFee(Models.STABLE_DIFFUSION || Models.LLAMA2 || Models.OPENLM);
// => 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`)
### `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

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)
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)
Loading