smartcontractkit / documentation

https://docs.chain.link The Chainlink developer documentation website for Smart Contract Devs and Node Operators

Welcome to Chainlink developer documentation repository. This repository is the source for developer documentation on docs.chain.link, which is a resource for smart contract developers and node operators building decentralized applications on several networks.

This documentation is open source. If you want to contribute tutorials or improvements, see the Contributing guide.

Note

The code samples in this documentation are examples for using Chainlink products and services and are provided to help you understand how to interact with Chainlink's systems and services so that you can integrate them into your own. These templates are provided "AS IS" and "AS AVAILABLE" without warranties of any kind, have not been audited, and may be missing key checks or error handling to make the usage of the product more clear. Do not use the example code in a production environment without completing your own audits and application of best practices. Neither Chainlink Labs, the Chainlink Foundation, nor Chainlink node operators are responsible for unintended outputs that are generated due to errors in code.

Developing

To run a local development environment, use the following command:

npm install && npm run dev

Docs architecture

• All docs are markdown and stored in /src/content.
• Navigation is JSON in /src/config/sidebar.ts

Deploy Preview

This repo is configured to automatically create a preview environment on Vercel when a PR is opened. After the deployment is approved, the Vercel bot will leave a comment with a link to the preview on your PR.

Deploying to Production

This repo is configured to automatically update the production (https://docs.chain.link) site when commits are pushed to the main branch.

documentation's Issues

Add link per section.

It would be great to have links to each section, for example, this image:

Could have the link:

https://docs.chain.link/docs/architecture-request-model/#ChainlinkClient

Tabs overflow

https://cl.fluin.io/docs/aggregator-job-bnbusd/

Add What's Next buttons

Links to What's Next are missing.

Env var docs are very out of date

Docs here are very out of date: https://docs.chain.link/docs/configuration-variables/

We need to go over them and update to be in line with what's in config.go. I can help with this, feel free to reach out.

Update Explorer used for Avalanche Fuji C-Chain price feeds

Currently, this documentation uses Avascan, however, our contracts are verified on the avax.network explorer.

Can we transition the links to avax explorer links?

AVAX/USD example:
https://cchain.explorer.avax-test.network/address/0x5498BB86BC934c8D34FDA08E81D444153d0D06aD/contracts

Remix examples missing faucet links?

https://remix.ethereum.org/#version=soljson-v0.6.6+commit.6c089d02.js&optimize=false&evmVersion=null&gist=536123b71478ad4442cfc4278e8de577&runs=200

We used to have faucet links in the comments. Did we decide to remove these? It seems like something that would be more helpful than not.

Navigation to scroll independently of content

The left menu is anchored to the main content, in that to scroll one; you must scroll both.

This means that the length of the page is dictated by the longest section (either menu or content). When you land on a page, you land at the top, which is desired for the main content. However, it is not for the menu, where the active menu item is often further down the page.

Some ideas:

• Have the height of the left menu navigation container be determined by the length of the main content.
• Make the menu itself scrollable, independent of the main content scroll.
• Auto-scroll the menu on page-load to vertically centre the active item.

Update Explorer used on Fantom to ftmscan

Currently, the docs use https://explorer.testnet.fantom.network/

However, it would be preferable to use https://testnet.ftmscan.com/

Update all examples to v0.8

• Chainlink API Call
• Chainlink Price Feeds
• Chainlink VRF
• Chainlink Keepers

Docs & gists

NEEDS VOTES: Rinkeby or goerli

Kovan has been having issues in the past, and it would be ideal to migrate our "banner" examples to rinkeby or goerli.

Looking for votes for rinkeby or goerli.

Rinkeby is used by projects like opensea, while goerli is the stomping grounds for ETH 2

Add page for Polygon / Matic ENS

ENS has been deployed to Polygon by our team.

Let's start with an ens-polygon.md page that's linked to on the ENS docs page.

Example web3 usage of the ENS on Polygon is here:

web3.eth.ens.registryAddress = "0x37C2058a99A8804bcEE54de1DbCEfC3FA866fF85"
web3.eth.ens.getAddress('eth-usd.data.eth')
  .then((address) => {
    console.log(address)
  })

Add Keepers FAQ

Getting this question asked a few times.

1. How often are they updated/call checkupkeep? (Every 20 blocks or so)
2. What's the delay between checkupkeep and perform upkeep? (a few seconds, and perhaps a few blocks depending on the layer 1)
3. Is there a way to verify that performUpkeep is actually run by a Keeper and the data it has passed is legit? (you'd modify your smart contract to only allow responses from those on the registry)
4. Costs

Fix ENS page

The HTML doesn't currently work

Image on adding LINK token to their contract.

https://docs.chain.link/docs/intermediates-tutorial/#6-obtaining-testnet-link

There is no image or description that shows a user how to add the LINK token to their metamask

Design feedback

Typography

• It looks inconsistent as there are various colors, sizes, and weights
• Line height looks really tight on some pages and not on others Example: https://cl.fluin.io/docs/node-operator-overview/
• Not enough margin between headings and paragraphs
• Groups of text should be visually separated so the document structure is more apparent
• Not enough margin been paragraphs, very hard to read Example: https://cl.fluin.io/docs/running-a-chainlink-node/

Images

• Images throughout the docs are really oversized and don’t have any additional whitespace around them, so they basically touch whatever element is above or below them Example: https://cl.fluin.io/docs/fulfilling-requests/
• Some images in inside of a bulleted list which looks weird, makes reading the list of bullets really difficult with how large the images are

Logo

• The developers wordmark is the fallback font on my end. Feel free to use the supplied Docs logo lockup.

New components styling

• The tabs, or the search-bar are not styled like Readme, but neither styled based on what we have on the Chainlink properties (eg. Data Feeds).

Incorrect path for anchor links

Overview

Some of the anchor links that refer to other pages or a section within the same page don't scroll to the required place when you select them because the path is incorrect.
Some of the pages include:

• https://docs.chain.link/docs/decentralized-oracles-ethereum-mainnet - adapters links
• https://docs.chain.link/docs/chainlink-alarm-clock/#section-chainlink-examples - request method URL

Removing #section inside the anchor should solve the issue.

Update style of top navigation links

• Color blue when hovering
• Increase size (change margin for padding) so click/touch targets are larger

Move "default" over to rinkeby

Kovan is a dying testnet. We should move.

L2 Flag for Optimism/Arbitrum

New Feature, once someone is assigned, need to have a quick sync

Add section to VRF for mapping requestId to answer

Give a demo of showing how to map your requestIds to the fulfilled randomness. ie something like:

mapping(bytes32 => uint256) requestIdToRandomNumber;

function fulfilRandomness(...)..{
requestIdToRandomNumber[requestId] =randomNumber;
}

Perhaps in a bestPractices section. We get this question in the discord fairly often.

Homepage div alignment is off

The centring of components seems to be slightly off on the home page.

Remove Node Op Mailing List links

Please remove the node op mailing list links from:

	modified:   docs/Node Operators/fulfilling-requests.md
	modified:   docs/Node Operators/node-operator-overview.md
	modified:   docs/Node Operators/running-a-chainlink-node.md
	modified:   docs/Oracle Jobs/adapters.md
	modified:   docs/Oracle Jobs/initiators.md
	modified:   docs/Oracle Jobs/job-specifications.md

Anchor links broken with update

On the previous version of the documentation, I was using anchor links like this one:
https://docs.chain.link/docs/binance-smart-chain-addresses/#testnet

As you'll see, when clicking this, it doesn't jump down to the referenced section anymore

Move all standard fonts to 16px

Re-add "What is Remix?" links under all "Deploy" buttons

Under every "Deploy this contract" button there used to be a "What is Remix?" link under it. This is very useful for beginners.

Contract addresses should open in a new window

add link to new VRF best practices

When we removed the VRF randomness expansion tip and moved it to the new section, some folks have been trouble finding it.

Let's add a link where the old description was to the new page & section.

https://github.com/smartcontractkit/documentation/pull/138/files#diff-7f4445627191c23a2b102a6d4ae6ec0991d4a16ae0cb91e2018099769b038cddL100-L114

Contract Addresses page missing links to Fantom & Arbitrum

Need to add:

• Fantom
• Arbitrum

on this page: https://docs.chain.link/docs/reference-contracts/

Active menu item glitch

Navigating to "Introduction to Data Provider Nodes" doesn't activate the ".active" tag on the menu item. This screenshot is taken whilst on that page.

Checksum all addresses

Right now, addresses are not checksummed, and a lot of compilers will throw errors if they are just copy pasted as so. For example:

The LINK token address of Rinkeby is marked as:
0x01be23585060835e02b77ef475b0cc51aa1e0709
And it should be:
0x01BE23585060835E02B77ef475b0Cc51aA1e0709

Warn customers of using equity and ETF Price Feeds

Add this message to relevant Price Feed pages:

Note, off-chain equity and ETF assets are only traded during standard market hours (9:30 am - 4 pm ET M-F). Using these feeds outside of those windows is not recommended.

Switch workflow action dependencies to shas

Use shas instead of tags or branches to improve security

Move data providers into a page

Take the list out of the navigation, and replace it with "Data Provider List" which links to a new page showcasing/listing the data providers.

Add devrel chainlink node API calls

1. Add more context to choosing a chainlink oracle using the chainlink devrel nodes
2. On the contract addresses page, add a code snippet of making API calls with the devrel nodes across testnets

Javascript button clicks open new window

Since this PR, javascript widget buttons on these pages do not work:

• Get the Latest Price - "Latest Price" button
• Get Historical Price - "Round 18446744073709562301" button
• ENS - "Lookup" button

It seems as though the code added in the breaking PR interprets these <a> tags as external links when they are not. There may be others that have not been noticed yet.

Add a "what is Chainlink" section & new engineer button

Intuition: Right now, when I go to the documentation of something someone tells me to checkout, the first thing I want to do is ask "where the hell am I?"

We should have some form of navigation to do so.

Additionally, on our landing page, we have 3 action items. https://docs.chain.link/
None of them are beginner-friendly. I'd like to test out adding a "New engineer? Start here" type button that will take them to our tutorials.

Add Heartbeat and Deviation to Contract Pages

data.chain.link is a very inefficient way for a customer to see heartbeat and deviation thresholds for feeds, and some feeds are not visualized on that page. As such, there is no way for a user to find this information in some cases, or in the best case scenario, it will take them a while to obtain the information.

I propose adding a column for deviation and a column for heartbeat on these pages, just like we have for decimals.

https://docs.chain.link/docs/ethereum-addresses/
https://docs.chain.link/docs/binance-smart-chain-addresses/
https://docs.chain.link/docs/matic-addresses/
https://docs.chain.link/docs/xdai-price-feeds/
https://docs.chain.link/docs/huobi-eco-chain-price-feeds/
https://docs.chain.link/docs/avalanche-price-feeds/

Update image for Price Aggregation

/docs/architecture-decentralized-model/ should display the new UI:

Combine all deferred main scripts into a single bundle using TypeScript

Add best practices page for VRF

New VRF Best Practices page, link to it from the main VRF page, and then extract the expand randomness notes too.

• “Getting more randomness (expanded randomness)”
• “Getting a random number within a range (using modulo)”
• “Having multiple requests for randomness in flight simultaneously (using maps and requestIds)”

Improve the workflow instructions for setting up a Chainlink node by providing Windows/Mac/Linux docker instructions

Navigation is not responsive

The navigation sidebar is not responsive and doesn't show up on mobile screens. Something like a hamburger menu would be a nice start.

Removed "intermediates" and "advanced" tutorials name

Intuition

1. "intermediates" isn't a word

We can just have in the "api call" tutorial that the randomness one is a prerequisite.

https://docs.chain.link/docs/intermediates-tutorial/

Add Fantom Testnet Token

NETWORK=fantomtestnet
CHAIN_ID=4002
LINK_ADDRESS=0xfaFedb041c0DD4fA2Dc0d87a6B0979Ee6FA7af5F

Community Faucet: https://linkfaucet.protofire.io/fantomtestnet
(Still being deployed)

Feed Registry

On-chain registry that maps token contract addresses to Chainlink Price Feeds

Dark mode

Dark mode, please. Weather NFT to whoever completes it.

End-to-end beginner walkthrough link is broken

https://docs.chain.link/docs/example-walkthrough

Mention the chainlink github has instructions for running from source

https://docs.chain.link/docs/running-a-chainlink-node/

https://github.com/smartcontractkit/chainlink#install

Remove all mentions of VRF@ email address

We are still receiving emails to that address from somewhere in the docs (or archived docs).

Remove all instances of this address.

Add clarity to VRF instructions

Today, a user launched a VRF request on Polygon mainnet using the Kovan configuration. We believe this stems from them following the get a random number documentation given that the default config uses Kovan's configuration.

Recommendation:

• Provide an explanation of what configurations need to be changed per chain
• Link the user to the VRF Contract Addresses page to find the configuration they need