Merge pull request #646 from api3dao/main

Deploy live site - 2023-10-10

CONTRIBUTING.md

@@ -0,0 +1,109 @@
+## Contributor's Guide
+
+Welcome to the API3 Documentation Repository. This guide will help you get
+started with contributing to the API3 documentation.
+
+## How to get started
+
+The API3 Docs uses [VitePress](https://vitepress.dev/), a Vue-powered static
+site generator. Follow the steps below to get started.
+
+Make sure to check out https://docs.api3.org/dev/ for more details and
+information about getting started and making a contribution to the API3 Docs.
+
+### Pre-requisites
+
+- [Node.js](https://nodejs.org/en/) (version 18 or higher).
+- Unix/macOS/WSL for the scripts to work properly.
+
+### Installation
+
+```bash
+yarn install
+```
+
+### Running the local development server
+
+Run the following command to start the local development server on port `5173`:
+
+```bash
+yarn docs:dev
+```
+
+### Structure
+
+The API3 Docs repository is structured as follows:
+
+- `/docs/explore`: Explore section within the API3 Docs.
+- `/docs/guides`: All the guides that demonstrate the use of Airnode, QRNG and
+  dAPIs.
+- `/docs/reference`: Contains the core documentation for Airnode, QRNG and
+  dAPIs.
+
+Each section will have a `sidebar.js` file that contains the sidebar structure
+for that section.
+
+`/_components`: Contains the custom vue components used in the API3 Docs.
+
+[Check this out](https://docs.api3.org/dev/docsets.html) for more info about the
+structure of the docs.
+
+### Building the static site
+
+```bash
+yarn docs:build
+```
+
+### Prettier Formatting
+
+Make sure to run the following command before submitting a PR to format the
+markdown. The Github action will check for prettier formatting:
+
+```bash
+yarn format
+```
+
+### Formatting and Styling
+
+You can use markdown to format the content. Check out the
+[docs development section](https://docs.api3.org/dev/) for more info. Some
+useful links:
+
+- [Page styling](https://docs.api3.org/dev/page-styling.html)
+- [Formatting guides](https://docs.api3.org/dev/guides-format.html)
+- [VitePress Containers](https://docs.api3.org/dev/containers.html)
+
+### Git Workflow:
+
+- `live-site` branch: for the current live site
+  [docs.api3.org](https://docs.api3.org)
+- `main` branch: for the staging site.
+
+[Check this out](https://docs.api3.org/dev/firebase.html#repo-branches) for more
+info about the branches.
+
+### Submitting an Issue
+
+You can submit an issue if you find any bugs or have any feature requests.
+Please make sure to check if the issue already exists before submitting a new
+one.
+
+You can:
+
+- Submit an issue for a bug.
+- Submit an issue for a feature request.
+- Submit an issue for a documentation request.
+
+### Making a PR
+
+After making all the changes, submit a PR against the `main` branch. The PR will
+be reviewed by the team and merged into the `main` branch. Make sure to link the
+issue in the PR description.
+
+You will then be able to see the changes with a Firebase preview link. Each PR
+has its own Firebase preview site. The URL will be available in the PR's
+comments.
+
+The changes will be deployed to the staging site. Once the changes are reviewed
+and approved, the changes will be merged from `main` into the `live-site` branch
+and deployed to the live site.

README.md

@@ -31,6 +31,11 @@ Firebase is used to host the `vitepress-docs` technical documentation.
 Additionally each PR has its own Firebase preview site. The URL will be
 available in the PR's comments.
 
+## Making a Contribution
+
+Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to make a
+contribution.
+
 ## Legacy documentation
 
 The original documentation for the repo `api3-docs` is now accessible via

docs/guides/qrng/index.md

@@ -6,6 +6,7 @@ pageHeader: Guides → QRNG
 path: /guides/qrng/index.html
 outline: deep
 tags:
+  - qrng, getting started
 ---
 
 <PageHeader/>
@@ -16,32 +17,64 @@ tags:
 
 # {{$frontmatter.title}}
 
-The [qrng-example<ExternalLinkImage/>](https://github.com/api3dao/qrng-example)
-project (GitHub repo) demonstrates how to build a smart contract (known as a
-requester) using the Airnode request–response protocol to receive QRNG services.
-It is recommended to run the example project to learn how it uses the QRNG
-service on a testnet, and read the associated README file. It also contains
-example code that will be useful when creating a requester (smart contract) that
-requests a quantum random number.
+This is the getting started section for QRNG along with some frequently asked
+questions. If you have a question that is not answered here, you can head over
+to our [Discord server](https://discord.com/invite/qnRrcfnm5W).
+
+## What is the QRNG?
+
+QRNG stands for Quantum Random Number Generator. It is a free to use service
+that provides quantum randomness on-chain. It is powered by
+[Airnode](/reference/airnode/latest/understand/index.md), the
+[first-party](/explore/airnode/why-first-party-oracles.md) oracle that is
+directly operated by the QRNG API providers. You can read more about QRNG
+[here](/reference/qrng/index.md).
+
+## How many providers are there for QRNG?
+
+Currently, there are 3 providers for QRNG:
+
+- [Australian National University<ExternalLinkImage/>](https://quantumnumbers.anu.edu.au/)
+- [Quintessence Labs<ExternalLinkImage/>](https://www.quintessencelabs.com/)
+- [Nodary (Testnet)<ExternalLinkImage/>](https://nodary.io/)
+
+[Click here to view the list of providers](/reference/qrng/providers.md).
+
+Both ANU and Quintessence Labs are running Airnodes in production serving 20+
+chains. Nodary is a testnet provider. It emulates QRNG using pseudorandom
+numbers on testnets chains.
+
+[Click here to view the list of chains where QRNG is available](/reference/qrng/chains.md).
+
+## How can you access QRNG?
+
+The [qrng-example<ExternalLinkImage/>](https://github.com/api3dao/qrng-example/)
+project demonstrates how to build a smart contract (known as a requester) using
+the Airnode
+[Request–Response Protocol (RRP)](/reference/airnode/latest/concepts/index.md)
+to access QRNG services. It is recommended to run the example project to learn
+how it uses the QRNG service on a testnet, and read the associated `README`
+file. It also contains example code that will be useful when creating a
+requester (smart contract) that requests a quantum random number.
 
 - [qrng-example/contracts/<ExternalLinkImage/>](https://github.com/api3dao/qrng-example/tree/main/contracts)
   - `QrngExamples.sol`: A sample requester used to call the QRNG service.
 - [qrng-example/deploy/<ExternalLinkImage/>](https://github.com/api3dao/qrng-example/tree/main/deploy)
   - `deploy.js`: Script that deploys a requester to a chain.
   - `setup.js`: Script that sets the parameters on the requester contract. These
-    parameters are used when calling the QRNG service.
-  - `fund.js`: Script that funds the wallet the requester uses to pay the gas
-    costs.
+    parameters are used when calling the QRNG Airnode.
+  - `fund.js`: Script that funds the `sponsorWallet` the requester uses to pay
+    the gas costs.
 
 ::: info Gas Costs
 
 Using the QRNG service is free, meaning there is no subscription fee to pay.
-There is a gas cost incurred on-chain when Airnode places the random number
+There is a gas cost incurred on-chain when Airnode submits the random number
 on-chain in response to a request, which the requester needs to pay for.
 
 :::
 
-## Sponsor Wallet
+### Sponsor Wallet
 
 The QRNG example project
 [sets the sponsor wallet<ExternalLinkImage/>](https://github.com/api3dao/qrng-example/blob/main/deploy/2_setup.js#L11-L28)
@@ -52,7 +85,7 @@ the [Using QRNG - Remix Example](/guides/qrng/qrng-remix/index.md) guide.
 
 <SponsorWalletWarning/>
 
-## Withdrawals
+### Withdrawals
 
 In the QRNG example project, the requester contract was written with the scope
 of demonstrating on-chain requests for random numbers.
@@ -65,16 +98,76 @@ additional functionality.
 :::
 
 For those inclined, withdrawal functionality can be added to the requester
-contract. First, funds must be transferred from `sponsorWallet` to `sponsor`.
-Since the requester contract is
-[set as the sponsor<ExternalLinkImage/>](https://github.com/api3dao/qrng-example/blob/46c93797902f25a46b73e40f8fa52c745b64ebb2/contracts/QrngExample.sol#L66),
-the requester contract needs to make the withdrawal request by calling
-`requestWithdrawal` from the
-[WithdrawalUtilsV0<ExternalLinkImage/>](https://github.com/api3dao/airnode/blob/4f3454cf40e1b0a1373e954df96ac22e1ce2e43f/packages/airnode-protocol/contracts/rrp/WithdrawalUtilsV0.sol#L27)
-contract. The `AirnodeRrpV0` contract inherits this contract and therefore the
-[published addresses](/reference/airnode/latest/) can be used. Second, a
-withdrawal function must be added to the requester contract such that the owner
-of the requester contract can transfer the requester contract balance to their
-address.
+contract. Check out the Requester contract in
+[Using QRNG - Remix Example](/guides/qrng/qrng-remix/index.md#_7-withdrawing-funds-from-the-sponsorwallet-optional)
+guide for an example on adding a withdrawal function to the requester contract
+and requesting a withdrawal from the Airnode.
+
+## How much does it cost to use QRNG?
+
+QRNG is free to use. You can use it as much as you want without paying anything.
+However, you will have to fund the `sponsorWallet` that incurs the gas fees for
+the transaction for the fulfillment of the request. A `sponsorWallet` address is
+derived from the requester contract address, the QRNG Airnode address and its
+extended public key (xpub). A sponsor wallet must be derived using the command
+[derive-sponsor-wallet-address](/reference/airnode/latest/packages/admin-cli.md#derive-sponsor-wallet-address)
+from the Admin CLI for your specific requester contract.
+
+You can refer to the funding table below to get an idea of how much you will
+have to fund the `sponsorWallet` for a request on a specific chain.
+
+::: details Funding table reference
+
+| Testnet                   | Amount | Unit  | Chain Id |
+| ------------------------- | ------ | ----- | -------- |
+| Ethereum-Goerli           | 0.1    | ETH   | 5        |
+| Ethereum-Sepolia          | 0.05   | SEP   | 11155111 |
+| RSK testnet               | 0.001  | tRBTC | 31       |
+| POA Network Sokol testnet | 0.05   | POA   | 77       |
+| BNB Chain testnet         | 0.005  | tBNB  | 97       |
+| Optimism testnet          | 0.05   | ETH   | 420      |
+| Moonbase Alpha testnet    | 0.1    | DEV   | 1287     |
+| Fantom testnet            | 0.5    | FTM   | 4002     |
+| Avalanche Fuji testnet    | 0.3    | AVAX  | 43113    |
+| Polygon Mumbai testnet    | 0.05   | MATIC | 80001    |
+| Milkomeda C1 testnet      | 0.5    | mTAda | 200101   |
+| Arbitrum testnet          | 0.01   | AGOR  | 421613   |
+
+:::
+
+You can read more about `sponsorWallet`
+[here](/reference/airnode/latest/concepts/sponsor.md#sponsorwallet).
+
+## How to request a single random number?
+
+To request a single random number, use the `endpointIdUint256` of the QRNG
+provider while making the request. You can find all the parameters of the QRNG
+providers [here](/reference/qrng/providers.md). To see how to code a basic QRNG
+Requester contract and make a request for a single random number,
+[click here](/guides/qrng/qrng-remix/index.md#to-request-a-single-random-number).
+
+## How to request multiple random numbers?
+
+Similar to requesting a single random number, you can request multiple random
+numbers by using the `endpointIdUint256Array` of the QRNG provider while making
+the request. It returns an array of random numbers. You will also have to
+mention the size of the array and encode it within the parameters. To see how to
+code a basic QRNG Requester contract and make a request for an array of random
+numbers,
+[click here](/guides/qrng/qrng-remix/index.md#to-request-an-array-of-random-numbers).
+
+## How to request a random number within a range?
+
+To have a random number within a specific range while making a request to the
+QRNG Airnode, you can use the `endpointIdUint256` to return a single random
+number and have it modulo the range difference and add the minimum number of the
+range. Refer to the code snippet below to see how to convert the random number
+and have it within the range `[x, y]`.
+
+```solidity
+uint256 randomNumber = (qrngUint256 % (y - x + 1)) + x;
+// y is the max number for the range, x is min number for the range.
+// the randomNumber will be in range [x, y].
+```
 
 <FlexEndTag/>

docs/guides/qrng/lottery-guide/index.md

@@ -25,8 +25,8 @@ these two tools is assumed.
 
 Currently, QRNG has three [providers](/reference/qrng/providers.md), two of
 which provide quantum random numbers. This guide will use the
-[Nodary provider<ExternalLinkImage/>](https://nodary.io/), available only on
-testnets, which returns a pseudorandom number.
+[Testnet Random Numbers](/reference/qrng/providers#testnet-random-numbers),
+available only on testnets, which returns a pseudorandom number.
 
 Anyone can choose a number 1–10,000 and buy a ticket to enter into a weekly
 lottery. The ticket revenue is collected into a pot in the contract. After 7
@@ -270,11 +270,11 @@ command
 from the Admin CLI. Use the value of the sponsor wallet address that the command
 outputs while making the request. **This wallet needs to be funded.**
 
-::: details Nodary QRNG Airnode Details
+::: details Testnet Random Numbers QRNG Airnode Details
 
 ```
-nodary QRNG Airnode Address = 0x6238772544f029ecaBfDED4300f13A3c4FE84E1D
-nodary QRNG Airnode XPUB = xpub6CuDdF9zdWTRuGybJPuZUGnU4suZowMmgu15bjFZT2o6PUtk4Lo78KGJUGBobz3pPKRaN9sLxzj21CMe6StP3zUsd8tWEJPgZBesYBMY7Wo
+Testnet Random Numbers QRNG Airnode Address = 0x6238772544f029ecaBfDED4300f13A3c4FE84E1D
+Testnet Random Numbers QRNG Airnode XPUB = xpub6CuDdF9zdWTRuGybJPuZUGnU4suZowMmgu15bjFZT2o6PUtk4Lo78KGJUGBobz3pPKRaN9sLxzj21CMe6StP3zUsd8tWEJPgZBesYBMY7Wo
 ```
 
 :::