# Tellor One-Stop Doc™

## The Ultimate Guide to hacking on Tellor <br> **FVM 2023 Edition*
*Hey Hackers! Welcome to your One-Stop Doc™ which includes everything you need to know about getting your hackathon project using Tellor’s oracle and ensuring you have an easy guided path to qualifying for a bounty.*

## Our bounties for FVM 2023:
**Challenge:**
Best use of Tellor oracle in your project built on FVM.
Prize Pool: $2500 (Up to 10 best teams, capped at $1000 per team)
To qualify:

**Winners will need to meet these 2 requirements:**
✅ Submit link to deployed and verified contract that integrates the [ “usingTellor” npm package](https://github.com/tellor-io/usingtellor)

✅ Submit a transaction hash of a tip to incentivize a report. Use [our guide](https://hackmd.io/ZKCzPtsSQiW6hgzvTqjwvA?both#How-to-Tip-Reporters)
to configure incentives for tipping/paying testnet reporters to provide your data.

>The key take-away is that we want to see true usage of Tellor demonstrated by those two requirements. (Don’t worry, we’ll guide you through it!)

## Now...we build.


One of the most basic use cases for oracles are *spotPrice* feeds ( [see list of readily available prices](https://hackmd.io/FAR5-PIdTD-CgESSRWhR5A) ). So this guide will focus on that.

However if you'd like to use Tellor for something that isn't a spot price or it happens to be an asset price not currently supported please use: *NumericApiResponse*.

> NumericApiResponse is a [query type](https://docs.tellor.io/tellor/getting-data/introduction#some-quick-definitions-before-we-move-on) specifically for testing that reports numerical values from any API to Tellor oracles. *Only use this query type for testing, as data sources with single points-of-failure shouldn't be used in production.*

## In this tutorial we'll go over:

- Setting up the initial toolkit you'll need to get up and running.
- An example integration of Tellor.
- Tipping to get a data report.

## UsingTellor

The first thing you'll want to do is install the basic tools necessary for using Tellor as your oracle. Use [this package](https://github.com/tellor-io/usingtellor) to install the Tellor user contracts:

`npm install usingtellor`

Once installed, this will allow your contracts to inherit the functions from the ['UsingTellor'.](https://github.com/tellor-io/usingtellor) contract.

Great! Now that you've got the tools ready, let's go through a simple exercise where we can retrieve the BTC/USD price :

### BTC/USD Price Example

Inherit the UsingTellor contract, passing the Tellor address as a constructor argument,

Here's an example contract & [github repo](https://github.com/tellor-io/sampleUsingTellor) to follow along with:

contract PriceContract is UsingTellor {

  uint256 public btcPrice;

  //This Contract now has access to all functions in UsingTellor

  constructor(address payable _tellorAddress) UsingTellor(_tellorAddress) {}

  function setBtcPrice() public {

    bytes memory _b = abi.encode("SpotPrice",abi.encode("btc","usd"));
    bytes32 _queryId = keccak256(_b);

    uint256 _timestamp;
    bytes memory _value;

    (_value, _timestamp) = getDataBefore(_queryId, block.timestamp - 15 minutes);

    require(_timestamp > 0, "No data exists");
    require(block.timestamp - _timestamp < 24 hours, "Data is too old");

    btcPrice = abi.decode(_value,(uint256));
  }
}

## To experience using Tellor w/ a demo contract, [ watch this video tutorial.](https://www.twitch.tv/videos/1809935703)
## Tipping

### Testnet Tokens
Once you've deployed your contract you'll need testnet tokens to tip reporters. You'll need Tellor Tributes (TRB) for this and of course the native token of your network. Here's how to get some:

### How to get Test TRB
Use the faucet function on [playground's token contract](https://hyperspace.filfox.info/en/address/0xe7147C5Ed14F545B4B17251992D1DB2bdfa26B6d)
[Click here](https://docs.tellor.io/tellor/the-basics/readme#need-testnet-tokens-trb) for more info

### How to Tip Reporters:

Via block explorer:

1. call approve with the tip amount in the token contract
* [Approve on Filecoin (Hyperspace) via remix](https://tellor.io/blog/how-to-create-token-approval-transactions-with-remix/)

2. call 'tip' in [autopay contract](https://docs.tellor.io/tellor/the-basics/contracts-reference)
<br>***Don't forget** to include a link to your tip tx in the *read.me* of your submitted project.

## 🎉🎉🎉 *Congrats! you're now an official Tellor user!*

### Need Some Inspiration?
Let's start with giving you an idea of what the Tellor oracle can provide…Anything! It just needs to be spec'd out.
But here’s some highlights:
* [Spot Prices](https://github.com/tellor-io/dataSpecs/blob/main/types/SpotPrice.md)
* [TWAP](https://github.com/tellor-io/dataSpecs/blob/main/types/TWAP.md)
* [Numeric API Responses
](https://github.com/tellor-io/dataSpecs/blob/main/types/NumericApiResponse.md)
* [Random Number Generator](https://github.com/tellor-io/dataSpecs/blob/main/types/TellorRNG.md)
* [Historical Gas price oracle](https://github.com/tellor-io/dataSpecs/blob/main/types/GasPriceOracle.md)
* [SnapshotVoteResults](https://github.com/tellor-io/dataSpecs/blob/main/types/Snapshot.md)
* [ChatGPT Responses](https://github.com/tellor-io/dataSpecs/blob/main/types/ChatGPTResponse.md)

>Tellor is extremely flexible, here's a full list of custom query types users have put together in the past [here.](https://github.com/tellor-io/dataSpecs/tree/main/types)

# **Extra Resources**

* **[List of readily available prices](https://hackmd.io/FAR5-PIdTD-CgESSRWhR5A)**

* **Tellor [Docs](https://docs.tellor.io)**

* **[List of addresses of all the networks Tellor currently supports](https://docs.tellor.io/tellor/the-basics/contracts-reference)**

* **Still have questions? Reach out to us in the #sponsor-tellor channel on the [#IPFS Discord](https://discord.gg/ipfs) or [Join the Tellor Discord](https://discord.gg/tellor)**

* **[Follow us on Twitter](https://twitter.com/wearetellor)**