# Oracle

## What is an Oracle?

A blockchain oracle is a service that connects blockchains to external data sources, allowing smart contracts to interact with real-world information. By providing data such as market prices, weather conditions, or sports scores, oracles enable blockchain applications to function beyond their isolated networks.

## Initiative

Theta Network currently lacks oracles, which are essential for connecting blockchains to real-world data. Integrating oracles can unlock numerous applications, such as decentralized finance (DeFi) services, gaming and more.

## Technical Specifications

To incorporate data from external sources, we designed an architecture where **four key actors** interact seamlessly.

<figure><img src="https://2470158326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fr1rpSLso3odY1qb1YN94%2Fuploads%2FHLrfZDKS1x7NuIbwRWSJ%2Foracle.png?alt=media&#x26;token=1176c34b-5e6e-4fea-8fbe-cd40bf1c3f80" alt="" width="563"><figcaption><p>Interaction</p></figcaption></figure>

### On-Chain

#### DogZilla Client

1. Initiates the process by calling the `createRequest` function on the O**racle Smart Contract**, specifying the required data.
2. Monitors the `RequestFilled` event from the **Oracle Smart Contract** to receive the off-chain data.

#### Oracle Smart Contract

1. Accepts the `createRequest` call from the **DogZilla Client** and stores the request.
2. Emits a `NewRequest` event to notify the **DogZilla Node** of the new request details.
3. Receives the `updateRequest` call from the **DogZilla Node** and updates the request with the retrieved off-chain data.
4. Emits a `RequestFilled` event to confirm the successful completion of the request and provide the requested data.

### Off-Chain

#### DogZilla Node

1. Listens for `NewRequest` events from the **Oracle Smart Contract** and processes the request.
2. Queries the **API Service** using the data from the on-chain request.
3. Receives the **JSON** response from the **API Service**.
4. Calls the `updateRequest` function on the **Oracle Smart Contract** with the received data.

#### API Service

An external off-chain service that supplies relevant data for application purposes.

1. Processes incoming queries.
2. Returns the requested data in **JSON** format.

## How can I use it?

To utilize our service, you can interact with our Oracle Smart Contract.

### Pricing

Each request sent to our Oracle Smart Contract incurs a service fee in <mark style="color:green;">DOGZ</mark> and a transaction fee in <mark style="color:orange;">TFUEL</mark>:

* **Service Fee:** 250 <mark style="color:green;">DOGZ</mark>
* **Transaction Fee:** 0.5 <mark style="color:orange;">TFUEL</mark>

### Client Integration

In your client application (using Ether.js, Web3.js, WAGMI, etc.), make a call to the `createRequest` function from our Oracle Smart Contract.

```solidity
function createRequest (string memory oracleType, uint256 [] memory args, bool priv) 
```

{% hint style="info" %}
The required arguments may vary depending on the oracle type. For detailed information, please refer to [#oracle-types](#oracle-types "mention").
{% endhint %}

Next, listen for the `RequestFilled` event, parse the response, and utilize the off-chain data as needed.

#### Private Request

If you want to perform a private request, set the `priv` argument to `true`. With this configuration, you will receive a different event called `RequestFilledPriv`. This event confirms the request but does not provide the data directly, as it remains private and is accessible only to the address that generated the request. To retrieve the off-chain data generated by the request, call the `readRequest` function.

```solidity
 function readRequest (uint256 id) external view returns (uint256)
```

### Solidity Integration

To integrate our Oracle Smart Contract with your custom Smart Contract, simply use our contract interface and instance.

{% hint style="info" %}
**Contract ->** 0xfb0996142e0324f93ad307c4cf14252746f395ad
{% endhint %}

```solidity
interface IDogOracle {
    ...
}

contract CustomContract {
    IDogOracle public oracle;
    
    constructor() {
        oracle = IDogOracle(0xfb0996142e0324f93ad307c4cf14252746f395ad);
    }
}
```

## Oracle Types

{% content-ref url="oracle/random-number" %}
[random-number](https://dogzilla.gitbook.io/documentation/dass/oracle/random-number)
{% endcontent-ref %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dogzilla.gitbook.io/documentation/dass/oracle.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.