diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..9f52d3e8 --- /dev/null +++ b/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. diff --git a/README.md b/README.md index d4eea726..9799324d 100644 --- a/README.md +++ b/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 diff --git a/docs/guides/qrng/index.md b/docs/guides/qrng/index.md index abcf2db2..aaa23665 100644 --- a/docs/guides/qrng/index.md +++ b/docs/guides/qrng/index.md @@ -6,6 +6,7 @@ pageHeader: Guides → QRNG path: /guides/qrng/index.html outline: deep tags: + - qrng, getting started --- @@ -16,32 +17,64 @@ tags: # {{$frontmatter.title}} -The [qrng-example](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](https://quantumnumbers.anu.edu.au/) +- [Quintessence Labs](https://www.quintessencelabs.com/) +- [Nodary (Testnet)](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](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/](https://github.com/api3dao/qrng-example/tree/main/contracts) - `QrngExamples.sol`: A sample requester used to call the QRNG service. - [qrng-example/deploy/](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](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. -## 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](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](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]. +```