From 37c563e00d84e5518d5743adb82d0cf045bc3455 Mon Sep 17 00:00:00 2001 From: Dwight Lyle Date: Mon, 4 Dec 2023 22:47:37 -0700 Subject: [PATCH 01/11] Add documentation for source imported packages --- .../tutorials/api-custom-response.mdx | 2 +- .../tutorials/api-multiple-calls.mdx | 2 +- .../tutorials/api-post-data.mdx | 2 +- .../tutorials/api-query-parameters.mdx | 2 +- .../tutorials/api-use-secrets.mdx | 2 +- .../tutorials/importing-packages.mdx | 149 ++++++++++++++++++ .../tutorials/simple-computation.mdx | 2 +- 7 files changed, 155 insertions(+), 6 deletions(-) create mode 100644 src/content/chainlink-functions/tutorials/importing-packages.mdx diff --git a/src/content/chainlink-functions/tutorials/api-custom-response.mdx b/src/content/chainlink-functions/tutorials/api-custom-response.mdx index f5f0119fa42..1dd84644cab 100644 --- a/src/content/chainlink-functions/tutorials/api-custom-response.mdx +++ b/src/content/chainlink-functions/tutorials/api-custom-response.mdx @@ -108,7 +108,7 @@ To run the example: #### source.js -The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/3-custom-response/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: The custom source code you want to execute in a Functions request can use vanilla [deno](https://deno.land/) but cannot use any require statements or imported modules. +The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/3-custom-response/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: The custom source code you want to execute in a Functions request can use vanilla [deno](https://deno.land/) but cannot use any require statements. This JavaScript source code uses [Functions.makeHttpRequest](/chainlink-functions/api-reference/javascript-source#http-requests) to make HTTP requests. To request the `ETH/USD` price, the source code calls the `https://min-api.cryptocompare.com/data/pricemultifull?fsyms=ETH&tsyms=USD` URL. If you read the [Functions.makeHttpRequest](/chainlink-functions/api-reference/javascript-source#http-requests) documentation, you see that you must provide the following parameters: diff --git a/src/content/chainlink-functions/tutorials/api-multiple-calls.mdx b/src/content/chainlink-functions/tutorials/api-multiple-calls.mdx index e4865e28a87..66c238ebc1b 100644 --- a/src/content/chainlink-functions/tutorials/api-multiple-calls.mdx +++ b/src/content/chainlink-functions/tutorials/api-multiple-calls.mdx @@ -127,7 +127,7 @@ To run the example: #### source.js -The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/8-multiple-apis/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: The custom source code you want to execute in a Functions request can use vanilla [deno](https://deno.land/) but cannot use any require statements or imported modules. +The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/8-multiple-apis/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: The custom source code you want to execute in a Functions request can use vanilla [deno](https://deno.land/) but cannot use any require statements. This JavaScript source code uses [Functions.makeHttpRequest](/chainlink-functions/api-reference/javascript-source#http-requests) to make HTTP requests. The source code fetches the BTC/USD price from different data sources: `https://pro-api.coinmarketcap.com/v1/cryptocurrency/quotes/latest/`, `https://api.coingecko.com/api/v3/simple/price`, and `https://api.coinpaprika.com/v1/tickers/btc-bitcoin` and then calculate the median price. you can read the API docs of [CoinMarketCap](https://coinmarketcap.com/api/documentation/v1/), [CoinGecko](https://www.coingecko.com/en/api/documentation), and [CoinPaprika](https://api.coinpaprika.com/) for details. diff --git a/src/content/chainlink-functions/tutorials/api-post-data.mdx b/src/content/chainlink-functions/tutorials/api-post-data.mdx index 6b2f3712af1..d4ea36eb657 100644 --- a/src/content/chainlink-functions/tutorials/api-post-data.mdx +++ b/src/content/chainlink-functions/tutorials/api-post-data.mdx @@ -117,7 +117,7 @@ To run the example: #### source.js -The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/4-post-data/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: The custom source code you want to execute in a Functions request can use vanilla [deno](https://deno.land/) but cannot use any require statements or imported modules. +The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/4-post-data/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: The custom source code you want to execute in a Functions request can use vanilla [deno](https://deno.land/) but cannot use any require statements. This JavaScript source code uses [Functions.makeHttpRequest](/chainlink-functions/api-reference/javascript-source#http-requests) to make HTTP requests. To request the `JP` country information, the source code calls the `https://countries.trevorblades.com/` URL and provides the query data in the HTTP request body. If you read the [Functions.makeHttpRequest](/chainlink-functions/api-reference/javascript-source#http-requests) documentation, you see that you must provide the following parameters: diff --git a/src/content/chainlink-functions/tutorials/api-query-parameters.mdx b/src/content/chainlink-functions/tutorials/api-query-parameters.mdx index 958412c9015..90e06cae880 100644 --- a/src/content/chainlink-functions/tutorials/api-query-parameters.mdx +++ b/src/content/chainlink-functions/tutorials/api-query-parameters.mdx @@ -101,7 +101,7 @@ To run the example: #### source.js -The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/2-call-api/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: The custom source code you want to execute in a Functions request can use vanilla [deno](https://deno.land/) but cannot use any require statements or imported modules. +The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/2-call-api/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: The custom source code you want to execute in a Functions request can use vanilla [deno](https://deno.land/) but cannot use any require statements. This JavaScript source code uses [Functions.makeHttpRequest](/chainlink-functions/api-reference/javascript-source#http-requests) to make HTTP requests. To request the `ETH/USD` price, the source code calls the `https://min-api.cryptocompare.com/data/pricemultifull?fsyms=ETH&tsyms=USD` URL. If you read the [Functions.makeHttpRequest](/chainlink-functions/api-reference/javascript-source#http-requests) documentation, you see that you must provide the following parameters: diff --git a/src/content/chainlink-functions/tutorials/api-use-secrets.mdx b/src/content/chainlink-functions/tutorials/api-use-secrets.mdx index cc2ac040d75..16cb9c0535e 100644 --- a/src/content/chainlink-functions/tutorials/api-use-secrets.mdx +++ b/src/content/chainlink-functions/tutorials/api-use-secrets.mdx @@ -122,7 +122,7 @@ To run the example: #### source.js -The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/5-use-secrets-threshold/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: The custom source code you want to execute in a Functions request can use vanilla [Deno](https://deno.land/) but cannot use any require statements or imported modules. +The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/5-use-secrets-threshold/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: The custom source code you want to execute in a Functions request can use vanilla [Deno](https://deno.land/) but cannot use any require statements. This JavaScript source code uses [Functions.makeHttpRequest](/chainlink-functions/api-reference/javascript-source#http-requests) to make HTTP requests. To request the `BTC` asset price, the source code calls the `https://pro-api.coinmarketcap.com/v1/cryptocurrency/quotes/latest/` URL. If you read the [Functions.makeHttpRequest](/chainlink-functions/api-reference/javascript-source#http-requests) documentation, you see that you must provide the following parameters: diff --git a/src/content/chainlink-functions/tutorials/importing-packages.mdx b/src/content/chainlink-functions/tutorials/importing-packages.mdx new file mode 100644 index 00000000000..e6ab5887718 --- /dev/null +++ b/src/content/chainlink-functions/tutorials/importing-packages.mdx @@ -0,0 +1,149 @@ +--- +section: chainlinkFunctions +date: Last Modified +title: "Using Imports with Functions" +metadata: + linkToWallet: true +whatsnext: + { + "Try out the Chainlink Functions Tutorials": "/chainlink-functions/tutorials", + "Read the Architecture to understand how Chainlink Functions operates": "/chainlink-functions/resources/architecture", + } +--- + +import { Aside, CopyText } from "@components" +import { Tabs } from "@components/Tabs" +import ChainlinkFunctions from "@features/chainlink-functions/common/ChainlinkFunctions.astro" + +This tutorial demonstrates different ways to import packages and use them to modify data before storing it on-chain. After [OCR](/chainlink-functions/resources/concepts) completes the off-chain processes, it returns the result to your smart contract. + + + +## Tutorial + +This tutorial demonstrates different ways to use imported packages in your Functions source code. Read the [Examine the code](#examine-the-code) section for a detailed description of the code example. + +You can locate the scripts used in this tutorial in the [_examples/11-package-imports_ directory](https://github.com/smartcontractkit/smart-contract-examples/tree/main/functions-examples/examples/11-package-imports). + +To run the example: + +1. Open the file `request.js`, which is located in the `11-package-imports` folder. +1. Replace the consumer contract address and the subscription ID with your own values. + + ```javascript + const consumerAddress = "0x8dFf78B7EE3128D00E90611FBeD20A71397064D9" // REPLACE this with your Functions consumer address + const subscriptionId = 3 // REPLACE this with your subscription ID + ``` + +1. Make a request: + + ```shell + node examples/11-package-imports/request.js + ``` + + The script runs your function in a sandbox environment before making an on-chain transaction: + + ```text + $ node examples/11-package-imports/request.js + secp256k1 unavailable, reverting to browser version + Start simulation... + Simulation result { + capturedTerminalOutput: 'Concatenated array: Hello, ,World,!\n' + + 'Joined string: Hello, ,World,!\n' + + 'Escaped string: Hello\\/ \\/World\\/\\x21\n', + responseBytesHexstring: '0x48656c6c6f5c2f205c2f576f726c645c2f5c783231' + } + ✅ Decoded response to string: Hello\/ \/World\/\x21 + + Estimate request costs... + Fulfillment cost estimated to 0.21366112757772 LINK + + Make request... + + ✅ Functions request sent! Transaction hash 0xdfb161de5a6ad34e58bb115dd07651a11d4cf4739652f509ecad78a1bf506e82. Waiting for a response... + See your request in the explorer https://mumbai.polygonscan.com/tx/0xdfb161de5a6ad34e58bb115dd07651a11d4cf4739652f509ecad78a1bf506e82 + + ✅ Request 0x3e51d48dae3443c81e6bb8e5220028db1fe24aacd73460a613a073325d2329e8 fulfilled with code: 0. Cost is 0.200435783655508510 LINK. Complete response: { + requestId: '0x3e51d48dae3443c81e6bb8e5220028db1fe24aacd73460a613a073325d2329e8', + subscriptionId: 3, + totalCostInJuels: 200435783655508510n, + responseBytesHexstring: '0x48656c6c6f5c2f205c2f576f726c645c2f5c783231', + errorString: '', + returnDataBytesHexstring: '0x', + fulfillmentCode: 0 + } + + ✅ Decoded response to string: Hello\/ \/World\/\x21 + ``` + + The output of the example gives you the following information: + + - Your request is first run on a sandbox environment to ensure it is correctly configured. + - The fulfillment costs are estimated before making the request. + - Your request was successfully sent to Chainlink Functions. The transaction in this example is `0xdfb161de5a6ad34e58bb115dd07651a11d4cf4739652f509ecad78a1bf506e82` and the request ID is `0xdfb161de5a6ad34e58bb115dd07651a11d4cf4739652f509ecad78a1bf506e82`. + + - The DON successfully fulfilled your request. The total cost was: `0.200435783655508510 LINK`. + - The consumer contract received a response in `bytes` with a value of `0x48656c6c6f5c2f205c2f576f726c645c2f5c783231`. Decoding it off-chain to `string` gives you a result: `Hello\/ \/World\/\x21`. + +## Examine the code + +### FunctionsConsumerExample.sol + + + +### JavaScript example + +#### source.js + +The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/11-package-imports/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: It is important to note that the custom source code you want to execute in a Functions request can use vanilla [Deno](https://deno.land/) but cannot use any require statements. + +#### request.js + +This explanation focuses on the [request.js](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/11-package-imports/request.js) script and shows how to use the [Chainlink Functions NPM package](https://github.com/smartcontractkit/functions-toolkit) in your own JavaScript/TypeScript project to send requests to a DON. The code is self-explanatory and has comments to help you understand all the steps. + +The script imports: + +- [path](https://nodejs.org/docs/latest/api/path.html) and [fs](https://nodejs.org/api/fs.html) : Used to read the [source file](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/11-package-imports/source.js). +- [ethers](https://docs.ethers.org/v5/): Ethers.js library, enables the script to interact with the blockchain. +- `@chainlink/functions-toolkit`: Chainlink Functions NPM package. All its utilities are documented in the [NPM README](https://github.com/smartcontractkit/functions-toolkit/blob/main/README.md). +- `@chainlink/env-enc`: A tool for loading and storing encrypted environment variables. Read the [official documentation](https://www.npmjs.com/package/@chainlink/env-enc) to learn more. +- `../abi/functionsClient.json`: The abi of the contract your script will interact with. **Note**: The script was tested with this [FunctionsConsumerExample contract](https://remix.ethereum.org/#url=https://docs.chain.link/samples/ChainlinkFunctions/FunctionsConsumerExample.sol). + +The script has two hardcoded values that you have to change using your own Functions consumer contract and subscription ID: + +```javascript +const consumerAddress = "0x8dFf78B7EE3128D00E90611FBeD20A71397064D9" // REPLACE this with your Functions consumer address +const subscriptionId = 3 // REPLACE this with your subscription ID +``` + +The primary function that the script executes is `makeRequestMumbai`. This function can be broken into five main parts: + +1. Definition of necessary identifiers: + + - `routerAddress`: Chainlink Functions router address on Polygon Mumbai. + - `donId`: Identifier of the DON that will fulfill your requests on Polygon Mumbai. + - `explorerUrl`: Block explorer url of Polygon Mumbai. + - `source`: The source code must be a string object. That's why we use `fs.readFileSync` to read `source.js` and then call `toString()` to get the content as a `string` object. + - `args`: During the execution of your function, These arguments are passed to the source code. + - `gasLimit`: Maximum gas that Chainlink Functions can use when transmitting the response to your contract. + - Initialization of ethers `signer` and `provider` objects. The signer is used to make transactions on the blockchain, and the provider reads data from the blockchain. + +1. Simulating your request in a local sandbox environment: + + - Use `simulateScript` from the Chainlink Functions NPM package. + - Read the `response` of the simulation. If successful, use the Functions NPM package `decodeResult` function and `ReturnType` enum to decode the response to the expected returned type (`ReturnType.uint256` in this example). + +1. Estimating the costs: + + - Initialize a `SubscriptionManager` from the Functions NPM package, then call the `estimateFunctionsRequestCost`. + - The response is returned in Juels (1 LINK = 10\*\*18 Juels). Use the `ethers.utils.formatEther` utility function to convert the output to LINK. + +1. Making a Chainlink Functions request: + + - Initialize your functions consumer contract using the contract address, abi, and ethers signer. + - Call the `sendRequest` function of your consumer contract. + +1. Waiting for the response: + + - Initialize a `ResponseListener` from the Functions NPM package and then call the `listenForResponseFromTransaction` function to wait for a response. By default, this function waits for five minutes. + - Upon reception of the response, use the Functions NPM package `decodeResult` function and `ReturnType` enum to decode the response to the expected returned type (`ReturnType.uint256` in this example). diff --git a/src/content/chainlink-functions/tutorials/simple-computation.mdx b/src/content/chainlink-functions/tutorials/simple-computation.mdx index 81824dbcff4..715968be8d5 100644 --- a/src/content/chainlink-functions/tutorials/simple-computation.mdx +++ b/src/content/chainlink-functions/tutorials/simple-computation.mdx @@ -100,7 +100,7 @@ To run the example: #### source.js -The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/1-simple-computation/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: It is important to note that the custom source code you want to execute in a Functions request can use vanilla [Deno](https://deno.land/) but cannot use any require statements or imported modules. +The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/1-simple-computation/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: It is important to note that the custom source code you want to execute in a Functions request can use vanilla [Deno](https://deno.land/) but cannot use any require statements. The main steps are: From 7ffce249ebd30e943bfa3e60e68b2b4c782e6d80 Mon Sep 17 00:00:00 2001 From: Dwight Lyle Date: Thu, 7 Dec 2023 10:23:08 -0700 Subject: [PATCH 02/11] Edits --- .../tutorials/api-custom-response.mdx | 2 +- .../tutorials/api-multiple-calls.mdx | 2 +- .../tutorials/api-post-data.mdx | 2 +- .../tutorials/api-query-parameters.mdx | 2 +- .../tutorials/api-use-secrets.mdx | 2 +- .../tutorials/importing-packages.mdx | 40 +++++++++---------- .../tutorials/simple-computation.mdx | 2 +- 7 files changed, 25 insertions(+), 27 deletions(-) diff --git a/src/content/chainlink-functions/tutorials/api-custom-response.mdx b/src/content/chainlink-functions/tutorials/api-custom-response.mdx index 1dd84644cab..c666d1f2ef8 100644 --- a/src/content/chainlink-functions/tutorials/api-custom-response.mdx +++ b/src/content/chainlink-functions/tutorials/api-custom-response.mdx @@ -108,7 +108,7 @@ To run the example: #### source.js -The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/3-custom-response/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: The custom source code you want to execute in a Functions request can use vanilla [deno](https://deno.land/) but cannot use any require statements. +The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/3-custom-response/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: The custom source code you want to execute in a Functions request can use vanilla [deno](https://deno.land/) but cannot use any require statements. Imported modules are supported only on testnets at this time. This JavaScript source code uses [Functions.makeHttpRequest](/chainlink-functions/api-reference/javascript-source#http-requests) to make HTTP requests. To request the `ETH/USD` price, the source code calls the `https://min-api.cryptocompare.com/data/pricemultifull?fsyms=ETH&tsyms=USD` URL. If you read the [Functions.makeHttpRequest](/chainlink-functions/api-reference/javascript-source#http-requests) documentation, you see that you must provide the following parameters: diff --git a/src/content/chainlink-functions/tutorials/api-multiple-calls.mdx b/src/content/chainlink-functions/tutorials/api-multiple-calls.mdx index 66c238ebc1b..ab2b7af58c4 100644 --- a/src/content/chainlink-functions/tutorials/api-multiple-calls.mdx +++ b/src/content/chainlink-functions/tutorials/api-multiple-calls.mdx @@ -127,7 +127,7 @@ To run the example: #### source.js -The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/8-multiple-apis/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: The custom source code you want to execute in a Functions request can use vanilla [deno](https://deno.land/) but cannot use any require statements. +The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/8-multiple-apis/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: The custom source code you want to execute in a Functions request can use vanilla [deno](https://deno.land/) but cannot use any require statements. Imported modules are supported only on testnets at this time. This JavaScript source code uses [Functions.makeHttpRequest](/chainlink-functions/api-reference/javascript-source#http-requests) to make HTTP requests. The source code fetches the BTC/USD price from different data sources: `https://pro-api.coinmarketcap.com/v1/cryptocurrency/quotes/latest/`, `https://api.coingecko.com/api/v3/simple/price`, and `https://api.coinpaprika.com/v1/tickers/btc-bitcoin` and then calculate the median price. you can read the API docs of [CoinMarketCap](https://coinmarketcap.com/api/documentation/v1/), [CoinGecko](https://www.coingecko.com/en/api/documentation), and [CoinPaprika](https://api.coinpaprika.com/) for details. diff --git a/src/content/chainlink-functions/tutorials/api-post-data.mdx b/src/content/chainlink-functions/tutorials/api-post-data.mdx index d4ea36eb657..70c9eafa5cd 100644 --- a/src/content/chainlink-functions/tutorials/api-post-data.mdx +++ b/src/content/chainlink-functions/tutorials/api-post-data.mdx @@ -117,7 +117,7 @@ To run the example: #### source.js -The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/4-post-data/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: The custom source code you want to execute in a Functions request can use vanilla [deno](https://deno.land/) but cannot use any require statements. +The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/4-post-data/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: The custom source code you want to execute in a Functions request can use vanilla [deno](https://deno.land/) but cannot use any require statements. Imported modules are supported only on testnets at this time. This JavaScript source code uses [Functions.makeHttpRequest](/chainlink-functions/api-reference/javascript-source#http-requests) to make HTTP requests. To request the `JP` country information, the source code calls the `https://countries.trevorblades.com/` URL and provides the query data in the HTTP request body. If you read the [Functions.makeHttpRequest](/chainlink-functions/api-reference/javascript-source#http-requests) documentation, you see that you must provide the following parameters: diff --git a/src/content/chainlink-functions/tutorials/api-query-parameters.mdx b/src/content/chainlink-functions/tutorials/api-query-parameters.mdx index 90e06cae880..4fec6716506 100644 --- a/src/content/chainlink-functions/tutorials/api-query-parameters.mdx +++ b/src/content/chainlink-functions/tutorials/api-query-parameters.mdx @@ -101,7 +101,7 @@ To run the example: #### source.js -The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/2-call-api/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: The custom source code you want to execute in a Functions request can use vanilla [deno](https://deno.land/) but cannot use any require statements. +The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/2-call-api/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: The custom source code you want to execute in a Functions request can use vanilla [deno](https://deno.land/) but cannot use any require statements. Imported modules are supported only on testnets at this time. This JavaScript source code uses [Functions.makeHttpRequest](/chainlink-functions/api-reference/javascript-source#http-requests) to make HTTP requests. To request the `ETH/USD` price, the source code calls the `https://min-api.cryptocompare.com/data/pricemultifull?fsyms=ETH&tsyms=USD` URL. If you read the [Functions.makeHttpRequest](/chainlink-functions/api-reference/javascript-source#http-requests) documentation, you see that you must provide the following parameters: diff --git a/src/content/chainlink-functions/tutorials/api-use-secrets.mdx b/src/content/chainlink-functions/tutorials/api-use-secrets.mdx index 16cb9c0535e..4c2fa06d51e 100644 --- a/src/content/chainlink-functions/tutorials/api-use-secrets.mdx +++ b/src/content/chainlink-functions/tutorials/api-use-secrets.mdx @@ -122,7 +122,7 @@ To run the example: #### source.js -The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/5-use-secrets-threshold/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: The custom source code you want to execute in a Functions request can use vanilla [Deno](https://deno.land/) but cannot use any require statements. +The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/5-use-secrets-threshold/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: The custom source code you want to execute in a Functions request can use vanilla [Deno](https://deno.land/) but cannot use any require statements. Imported modules are supported only on testnets at this time. This JavaScript source code uses [Functions.makeHttpRequest](/chainlink-functions/api-reference/javascript-source#http-requests) to make HTTP requests. To request the `BTC` asset price, the source code calls the `https://pro-api.coinmarketcap.com/v1/cryptocurrency/quotes/latest/` URL. If you read the [Functions.makeHttpRequest](/chainlink-functions/api-reference/javascript-source#http-requests) documentation, you see that you must provide the following parameters: diff --git a/src/content/chainlink-functions/tutorials/importing-packages.mdx b/src/content/chainlink-functions/tutorials/importing-packages.mdx index e6ab5887718..c281ff44c0a 100644 --- a/src/content/chainlink-functions/tutorials/importing-packages.mdx +++ b/src/content/chainlink-functions/tutorials/importing-packages.mdx @@ -48,42 +48,40 @@ To run the example: secp256k1 unavailable, reverting to browser version Start simulation... Simulation result { - capturedTerminalOutput: 'Concatenated array: Hello, ,World,!\n' + - 'Joined string: Hello, ,World,!\n' + - 'Escaped string: Hello\\/ \\/World\\/\\x21\n', - responseBytesHexstring: '0x48656c6c6f5c2f205c2f576f726c645c2f5c783231' + capturedTerminalOutput: 'Fetched BTC / USD price: 4367193987453\n', + responseBytesHexstring: '0x000000000000000000000000000000000000000000000000000003f8d10bd97d' } - ✅ Decoded response to string: Hello\/ \/World\/\x21 + ✅ Decoded response to int256: 4367193987453n Estimate request costs... - Fulfillment cost estimated to 0.21366112757772 LINK + Fulfillment cost estimated to 0.20243353895715 LINK Make request... - ✅ Functions request sent! Transaction hash 0xdfb161de5a6ad34e58bb115dd07651a11d4cf4739652f509ecad78a1bf506e82. Waiting for a response... - See your request in the explorer https://mumbai.polygonscan.com/tx/0xdfb161de5a6ad34e58bb115dd07651a11d4cf4739652f509ecad78a1bf506e82 - - ✅ Request 0x3e51d48dae3443c81e6bb8e5220028db1fe24aacd73460a613a073325d2329e8 fulfilled with code: 0. Cost is 0.200435783655508510 LINK. Complete response: { - requestId: '0x3e51d48dae3443c81e6bb8e5220028db1fe24aacd73460a613a073325d2329e8', - subscriptionId: 3, - totalCostInJuels: 200435783655508510n, - responseBytesHexstring: '0x48656c6c6f5c2f205c2f576f726c645c2f5c783231', - errorString: '', - returnDataBytesHexstring: '0x', - fulfillmentCode: 0 + ✅ Functions request sent! Transaction hash 0xed3d0419189c012ce852b37b51d47bdcd80f06a4749b4c01a81a3f5fb06139e3. Waiting for a response... + See your request in the explorer https://mumbai.polygonscan.com/tx/0xed3d0419189c012ce852b37b51d47bdcd80f06a4749b4c01a81a3f5fb06139e3 + + ✅ Request 0xa8a7bec42edc16cf549f69e734161f2f2550a1057bb4060611a8043253ee61ef successfully fulfilled. Cost is 0.200014890551438381 LINK.Complete reponse: { + requestId: '0xa8a7bec42edc16cf549f69e734161f2f2550a1057bb4060611a8043253ee61ef', + subscriptionId: 38, + totalCostInJuels: 200014890551438381n, + responseBytesHexstring: '0x000000000000000000000000000000000000000000000000000003f8d10bd97d', + errorString: '', + returnDataBytesHexstring: '0x', + fulfillmentCode: 0 } - ✅ Decoded response to string: Hello\/ \/World\/\x21 + ✅ Decoded response to int256: 4367193987453n ``` The output of the example gives you the following information: - Your request is first run on a sandbox environment to ensure it is correctly configured. - The fulfillment costs are estimated before making the request. - - Your request was successfully sent to Chainlink Functions. The transaction in this example is `0xdfb161de5a6ad34e58bb115dd07651a11d4cf4739652f509ecad78a1bf506e82` and the request ID is `0xdfb161de5a6ad34e58bb115dd07651a11d4cf4739652f509ecad78a1bf506e82`. + - Your request was successfully sent to Chainlink Functions. The transaction in this example is `0xed3d0419189c012ce852b37b51d47bdcd80f06a4749b4c01a81a3f5fb06139e3` and the request ID is `0xdfb161de5a6ad34e58bb115dd07651a11d4cf4739652f509ecad78a1bf506e82`. - The DON successfully fulfilled your request. The total cost was: `0.200435783655508510 LINK`. - - The consumer contract received a response in `bytes` with a value of `0x48656c6c6f5c2f205c2f576f726c645c2f5c783231`. Decoding it off-chain to `string` gives you a result: `Hello\/ \/World\/\x21`. + - The consumer contract received a response in `bytes` with a value of `0xa8a7bec42edc16cf549f69e734161f2f2550a1057bb4060611a8043253ee61ef`. Decoding it off-chain to `int256` gives you a result: `4367193987453`. ## Examine the code @@ -95,7 +93,7 @@ To run the example: #### source.js -The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/11-package-imports/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: It is important to note that the custom source code you want to execute in a Functions request can use vanilla [Deno](https://deno.land/) but cannot use any require statements. +The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/11-package-imports/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: It is important to note that the custom source code you want to execute in a Functions request can use vanilla [Deno](https://deno.land/) but cannot use any require statements. Imported modules are supported only on testnets at this time. #### request.js diff --git a/src/content/chainlink-functions/tutorials/simple-computation.mdx b/src/content/chainlink-functions/tutorials/simple-computation.mdx index 715968be8d5..810d74fd38c 100644 --- a/src/content/chainlink-functions/tutorials/simple-computation.mdx +++ b/src/content/chainlink-functions/tutorials/simple-computation.mdx @@ -100,7 +100,7 @@ To run the example: #### source.js -The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/1-simple-computation/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: It is important to note that the custom source code you want to execute in a Functions request can use vanilla [Deno](https://deno.land/) but cannot use any require statements. +The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/1-simple-computation/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: It is important to note that the custom source code you want to execute in a Functions request can use vanilla [Deno](https://deno.land/) but cannot use any require statements. Imported modules are supported only on testnets at this time. The main steps are: From 9e3deb206ca428da8e244784b514e2f10842165f Mon Sep 17 00:00:00 2001 From: Dwight Lyle Date: Thu, 7 Dec 2023 12:10:41 -0700 Subject: [PATCH 03/11] Edits --- .../resources/release-notes.mdx | 6 ++++++ .../tutorials/importing-packages.mdx | 21 +++++++++++++++++-- 2 files changed, 25 insertions(+), 2 deletions(-) diff --git a/src/content/chainlink-functions/resources/release-notes.mdx b/src/content/chainlink-functions/resources/release-notes.mdx index 77eaa7eb8f9..5901540e4a9 100644 --- a/src/content/chainlink-functions/resources/release-notes.mdx +++ b/src/content/chainlink-functions/resources/release-notes.mdx @@ -6,6 +6,12 @@ title: "Chainlink Functions Release Notes" import { Aside } from "@components" +## Module import support on testnets - 2023-10-07 + +You can use module imports with Chainlink Functions source code on testnet networks. See the [Using Imports with Functions](/chainlink-functions/tutorials/importing-packages) tutorial to see and example of how to import and use imported modules with your Functions source code. This feature requires the [Functions Toolkit NPM package](https://www.npmjs.com/package/@chainlink/functions-toolkit/v/0.2.7) `v0.2.7` or later. + +This feature is available only on testnets. Imported modules will not import or execute on mainnet networks at this time. + ## Open Beta - 2023-09-29 - Chainlink Functions is available as an open beta on the following blockchains: diff --git a/src/content/chainlink-functions/tutorials/importing-packages.mdx b/src/content/chainlink-functions/tutorials/importing-packages.mdx index c281ff44c0a..9ab59594d29 100644 --- a/src/content/chainlink-functions/tutorials/importing-packages.mdx +++ b/src/content/chainlink-functions/tutorials/importing-packages.mdx @@ -15,13 +15,30 @@ import { Aside, CopyText } from "@components" import { Tabs } from "@components/Tabs" import ChainlinkFunctions from "@features/chainlink-functions/common/ChainlinkFunctions.astro" -This tutorial demonstrates different ways to import packages and use them to modify data before storing it on-chain. After [OCR](/chainlink-functions/resources/concepts) completes the off-chain processes, it returns the result to your smart contract. +This tutorial demonstrates how to import modules and use them with your Functions source code. Modules that are imported into Functions source code must meet the following requirements: + +- Each import must be 10 MB or less in size. +- Up to 20 imports total are supported. +- Deno supports [ESM compatible NPM imports](https://docs.deno.com/runtime/manual/node/npm_specifiers) and some [standard Node modules](https://docs.deno.com/runtime/manual/node/node_specifiers). See the [Compatability List](https://docs.deno.com/runtime/manual/node/compatibility) for details. +- Third-party modules are imported at runtime, so import statements must use asynchronous logic like the following examples: + - Importing from `demo.land`: `const { escape } = await import("https://deno.land/std/regexp/mod.ts");` + - ESM-compatible packages: `const { format } = await import("npm:date-fns");` + - Standard Node modules: `const path = await import("node:path");` + - CDN imports: `const lodash = await import("http://cdn.skypack.dev/lodash");` +- Imported modules abide by all sandbox restrictions and do not have access to the file system, environment variables, or any other Deno permissions. + + ## Tutorial -This tutorial demonstrates different ways to use imported packages in your Functions source code. Read the [Examine the code](#examine-the-code) section for a detailed description of the code example. +This example imports [ethers](https://www.npmjs.com/package/ethers) and demonstrates how to call a smart contract functions using a JSON RPC provider to call an on-chain function. In this example, the source code calls the [`latestRoundData()` function](/data-feeds/api-reference#latestrounddata) from the `AggregatorV3Interface`. Read the [Examine the code](#examine-the-code) section for a detailed description of the code example. You can locate the scripts used in this tutorial in the [_examples/11-package-imports_ directory](https://github.com/smartcontractkit/smart-contract-examples/tree/main/functions-examples/examples/11-package-imports). From ebfbce2c6792fa1475d523617acfe85c2c8f90ab Mon Sep 17 00:00:00 2001 From: Dwight Lyle Date: Thu, 7 Dec 2023 12:44:05 -0700 Subject: [PATCH 04/11] Edits --- .../resources/release-notes.mdx | 2 +- .../tutorials/importing-packages.mdx | 39 ++++++++++++++++++- 2 files changed, 38 insertions(+), 3 deletions(-) diff --git a/src/content/chainlink-functions/resources/release-notes.mdx b/src/content/chainlink-functions/resources/release-notes.mdx index 5901540e4a9..b815a28fa22 100644 --- a/src/content/chainlink-functions/resources/release-notes.mdx +++ b/src/content/chainlink-functions/resources/release-notes.mdx @@ -10,7 +10,7 @@ import { Aside } from "@components" You can use module imports with Chainlink Functions source code on testnet networks. See the [Using Imports with Functions](/chainlink-functions/tutorials/importing-packages) tutorial to see and example of how to import and use imported modules with your Functions source code. This feature requires the [Functions Toolkit NPM package](https://www.npmjs.com/package/@chainlink/functions-toolkit/v/0.2.7) `v0.2.7` or later. -This feature is available only on testnets. Imported modules will not import or execute on mainnet networks at this time. +This feature is available only on testnets. Modules will not import or execute on Functions requests for mainnet networks at this time. ## Open Beta - 2023-09-29 diff --git a/src/content/chainlink-functions/tutorials/importing-packages.mdx b/src/content/chainlink-functions/tutorials/importing-packages.mdx index 9ab59594d29..ca2fc621c65 100644 --- a/src/content/chainlink-functions/tutorials/importing-packages.mdx +++ b/src/content/chainlink-functions/tutorials/importing-packages.mdx @@ -112,6 +112,41 @@ To run the example: The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/11-package-imports/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: It is important to note that the custom source code you want to execute in a Functions request can use vanilla [Deno](https://deno.land/) but cannot use any require statements. Imported modules are supported only on testnets at this time. +The example `source.js` file uses an Ethers JSON RPC call to the [`latestRoundData()` function](/data-feeds/api-reference#latestrounddata) of a [Chainlink Data Feed](/data-feeds). The request requires a few modifications to work in the Chainlink Functions environment. For example, the `JsonRpcProvider` class must be modified to handle the request asynchronously. + +```javascript +// Chainlink Functions compatible Ethers JSON RPC provider class +// (this is required for making Ethers RPC calls with Chainlink Functions) +class FunctionsJsonRpcProvider extends ethers.JsonRpcProvider { + constructor(url) { + super(url) + this.url = url + } + async _send(payload: ethers.JsonRpcPayload | Array): Promise> { + let resp = await fetch(this.url, { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify(payload), + }) + return resp.json() + } +} +``` + +After the class is extended, you can initialize the provider object and await the response. + +```javascript +const provider = new FunctionsJsonRpcProvider(RPC_URL) +const dataFeedContract = new ethers.Contract(CONTRACT_ADDRESS, abi, provider) +const dataFeedResponse = await dataFeedContract.latestRoundData() +``` + +In this example, the contract returns an `int256` value. Encode the value so request.js can properly decode it. + +```javascript +return Functions.encodeInt256(dataFeedResponse.answer) +``` + #### request.js This explanation focuses on the [request.js](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/11-package-imports/request.js) script and shows how to use the [Chainlink Functions NPM package](https://github.com/smartcontractkit/functions-toolkit) in your own JavaScript/TypeScript project to send requests to a DON. The code is self-explanatory and has comments to help you understand all the steps. @@ -146,7 +181,7 @@ The primary function that the script executes is `makeRequestMumbai`. This funct 1. Simulating your request in a local sandbox environment: - Use `simulateScript` from the Chainlink Functions NPM package. - - Read the `response` of the simulation. If successful, use the Functions NPM package `decodeResult` function and `ReturnType` enum to decode the response to the expected returned type (`ReturnType.uint256` in this example). + - Read the `response` of the simulation. If successful, use the Functions NPM package `decodeResult` function and `ReturnType` enum to decode the response to the expected returned type (`ReturnType.int256` in this example). 1. Estimating the costs: @@ -161,4 +196,4 @@ The primary function that the script executes is `makeRequestMumbai`. This funct 1. Waiting for the response: - Initialize a `ResponseListener` from the Functions NPM package and then call the `listenForResponseFromTransaction` function to wait for a response. By default, this function waits for five minutes. - - Upon reception of the response, use the Functions NPM package `decodeResult` function and `ReturnType` enum to decode the response to the expected returned type (`ReturnType.uint256` in this example). + - Upon reception of the response, use the Functions NPM package `decodeResult` function and `ReturnType` enum to decode the response to the expected returned type (`ReturnType.int256` in this example). From 49e3f534790064572d091a8403fd4a3d2e6694f4 Mon Sep 17 00:00:00 2001 From: Dwight Lyle Date: Wed, 13 Dec 2023 10:58:45 -0700 Subject: [PATCH 05/11] Edits --- .../chainlink-functions/tutorials/api-custom-response.mdx | 2 +- .../chainlink-functions/tutorials/api-multiple-calls.mdx | 2 +- src/content/chainlink-functions/tutorials/api-post-data.mdx | 2 +- .../chainlink-functions/tutorials/api-query-parameters.mdx | 2 +- src/content/chainlink-functions/tutorials/api-use-secrets.mdx | 2 +- .../chainlink-functions/tutorials/importing-packages.mdx | 4 ++-- .../chainlink-functions/tutorials/simple-computation.mdx | 2 +- 7 files changed, 8 insertions(+), 8 deletions(-) diff --git a/src/content/chainlink-functions/tutorials/api-custom-response.mdx b/src/content/chainlink-functions/tutorials/api-custom-response.mdx index c666d1f2ef8..5ce2e0d500f 100644 --- a/src/content/chainlink-functions/tutorials/api-custom-response.mdx +++ b/src/content/chainlink-functions/tutorials/api-custom-response.mdx @@ -108,7 +108,7 @@ To run the example: #### source.js -The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/3-custom-response/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: The custom source code you want to execute in a Functions request can use vanilla [deno](https://deno.land/) but cannot use any require statements. Imported modules are supported only on testnets at this time. +The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/3-custom-response/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: Functions requests with custom source code can use vanilla [Deno](https://deno.land/) but cannot use any require statements. Import statements and imported modules are supported only on testnets. This JavaScript source code uses [Functions.makeHttpRequest](/chainlink-functions/api-reference/javascript-source#http-requests) to make HTTP requests. To request the `ETH/USD` price, the source code calls the `https://min-api.cryptocompare.com/data/pricemultifull?fsyms=ETH&tsyms=USD` URL. If you read the [Functions.makeHttpRequest](/chainlink-functions/api-reference/javascript-source#http-requests) documentation, you see that you must provide the following parameters: diff --git a/src/content/chainlink-functions/tutorials/api-multiple-calls.mdx b/src/content/chainlink-functions/tutorials/api-multiple-calls.mdx index ab2b7af58c4..a15365b2c18 100644 --- a/src/content/chainlink-functions/tutorials/api-multiple-calls.mdx +++ b/src/content/chainlink-functions/tutorials/api-multiple-calls.mdx @@ -127,7 +127,7 @@ To run the example: #### source.js -The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/8-multiple-apis/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: The custom source code you want to execute in a Functions request can use vanilla [deno](https://deno.land/) but cannot use any require statements. Imported modules are supported only on testnets at this time. +The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/8-multiple-apis/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: Functions requests with custom source code can use vanilla [Deno](https://deno.land/) but cannot use any require statements. Import statements and imported modules are supported only on testnets. This JavaScript source code uses [Functions.makeHttpRequest](/chainlink-functions/api-reference/javascript-source#http-requests) to make HTTP requests. The source code fetches the BTC/USD price from different data sources: `https://pro-api.coinmarketcap.com/v1/cryptocurrency/quotes/latest/`, `https://api.coingecko.com/api/v3/simple/price`, and `https://api.coinpaprika.com/v1/tickers/btc-bitcoin` and then calculate the median price. you can read the API docs of [CoinMarketCap](https://coinmarketcap.com/api/documentation/v1/), [CoinGecko](https://www.coingecko.com/en/api/documentation), and [CoinPaprika](https://api.coinpaprika.com/) for details. diff --git a/src/content/chainlink-functions/tutorials/api-post-data.mdx b/src/content/chainlink-functions/tutorials/api-post-data.mdx index 70c9eafa5cd..910a140f54a 100644 --- a/src/content/chainlink-functions/tutorials/api-post-data.mdx +++ b/src/content/chainlink-functions/tutorials/api-post-data.mdx @@ -117,7 +117,7 @@ To run the example: #### source.js -The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/4-post-data/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: The custom source code you want to execute in a Functions request can use vanilla [deno](https://deno.land/) but cannot use any require statements. Imported modules are supported only on testnets at this time. +The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/4-post-data/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: Functions requests with custom source code can use vanilla [Deno](https://deno.land/) but cannot use any require statements. Import statements and imported modules are supported only on testnets. This JavaScript source code uses [Functions.makeHttpRequest](/chainlink-functions/api-reference/javascript-source#http-requests) to make HTTP requests. To request the `JP` country information, the source code calls the `https://countries.trevorblades.com/` URL and provides the query data in the HTTP request body. If you read the [Functions.makeHttpRequest](/chainlink-functions/api-reference/javascript-source#http-requests) documentation, you see that you must provide the following parameters: diff --git a/src/content/chainlink-functions/tutorials/api-query-parameters.mdx b/src/content/chainlink-functions/tutorials/api-query-parameters.mdx index 4fec6716506..7798b401fcf 100644 --- a/src/content/chainlink-functions/tutorials/api-query-parameters.mdx +++ b/src/content/chainlink-functions/tutorials/api-query-parameters.mdx @@ -101,7 +101,7 @@ To run the example: #### source.js -The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/2-call-api/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: The custom source code you want to execute in a Functions request can use vanilla [deno](https://deno.land/) but cannot use any require statements. Imported modules are supported only on testnets at this time. +The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/2-call-api/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: Functions requests with custom source code can use vanilla [Deno](https://deno.land/) but cannot use any require statements. Import statements and imported modules are supported only on testnets. This JavaScript source code uses [Functions.makeHttpRequest](/chainlink-functions/api-reference/javascript-source#http-requests) to make HTTP requests. To request the `ETH/USD` price, the source code calls the `https://min-api.cryptocompare.com/data/pricemultifull?fsyms=ETH&tsyms=USD` URL. If you read the [Functions.makeHttpRequest](/chainlink-functions/api-reference/javascript-source#http-requests) documentation, you see that you must provide the following parameters: diff --git a/src/content/chainlink-functions/tutorials/api-use-secrets.mdx b/src/content/chainlink-functions/tutorials/api-use-secrets.mdx index 4c2fa06d51e..173fb3946cf 100644 --- a/src/content/chainlink-functions/tutorials/api-use-secrets.mdx +++ b/src/content/chainlink-functions/tutorials/api-use-secrets.mdx @@ -122,7 +122,7 @@ To run the example: #### source.js -The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/5-use-secrets-threshold/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: The custom source code you want to execute in a Functions request can use vanilla [Deno](https://deno.land/) but cannot use any require statements. Imported modules are supported only on testnets at this time. +The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/5-use-secrets-threshold/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: Functions requests with custom source code can use vanilla [Deno](https://deno.land/) but cannot use any require statements. Import statements and imported modules are supported only on testnets. This JavaScript source code uses [Functions.makeHttpRequest](/chainlink-functions/api-reference/javascript-source#http-requests) to make HTTP requests. To request the `BTC` asset price, the source code calls the `https://pro-api.coinmarketcap.com/v1/cryptocurrency/quotes/latest/` URL. If you read the [Functions.makeHttpRequest](/chainlink-functions/api-reference/javascript-source#http-requests) documentation, you see that you must provide the following parameters: diff --git a/src/content/chainlink-functions/tutorials/importing-packages.mdx b/src/content/chainlink-functions/tutorials/importing-packages.mdx index ca2fc621c65..f7b3ffe4cf6 100644 --- a/src/content/chainlink-functions/tutorials/importing-packages.mdx +++ b/src/content/chainlink-functions/tutorials/importing-packages.mdx @@ -21,7 +21,7 @@ This tutorial demonstrates how to import modules and use them with your Function - Up to 20 imports total are supported. - Deno supports [ESM compatible NPM imports](https://docs.deno.com/runtime/manual/node/npm_specifiers) and some [standard Node modules](https://docs.deno.com/runtime/manual/node/node_specifiers). See the [Compatability List](https://docs.deno.com/runtime/manual/node/compatibility) for details. - Third-party modules are imported at runtime, so import statements must use asynchronous logic like the following examples: - - Importing from `demo.land`: `const { escape } = await import("https://deno.land/std/regexp/mod.ts");` + - Importing from `deno.land`: `const { escape } = await import("https://deno.land/std/regexp/mod.ts");` - ESM-compatible packages: `const { format } = await import("npm:date-fns");` - Standard Node modules: `const path = await import("node:path");` - CDN imports: `const lodash = await import("http://cdn.skypack.dev/lodash");` @@ -110,7 +110,7 @@ To run the example: #### source.js -The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/11-package-imports/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: It is important to note that the custom source code you want to execute in a Functions request can use vanilla [Deno](https://deno.land/) but cannot use any require statements. Imported modules are supported only on testnets at this time. +The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/11-package-imports/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: Functions requests with custom source code can use vanilla [Deno](https://deno.land/) but cannot use any require statements. Import statements and imported modules are supported only on testnets. The example `source.js` file uses an Ethers JSON RPC call to the [`latestRoundData()` function](/data-feeds/api-reference#latestrounddata) of a [Chainlink Data Feed](/data-feeds). The request requires a few modifications to work in the Chainlink Functions environment. For example, the `JsonRpcProvider` class must be modified to handle the request asynchronously. diff --git a/src/content/chainlink-functions/tutorials/simple-computation.mdx b/src/content/chainlink-functions/tutorials/simple-computation.mdx index 810d74fd38c..e1f2b0035b9 100644 --- a/src/content/chainlink-functions/tutorials/simple-computation.mdx +++ b/src/content/chainlink-functions/tutorials/simple-computation.mdx @@ -100,7 +100,7 @@ To run the example: #### source.js -The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/1-simple-computation/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: It is important to note that the custom source code you want to execute in a Functions request can use vanilla [Deno](https://deno.land/) but cannot use any require statements. Imported modules are supported only on testnets at this time. +The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/1-simple-computation/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: Functions requests with custom source code can use vanilla [Deno](https://deno.land/) but cannot use any require statements. Import statements and imported modules are supported only on testnets. The main steps are: From 280fb29d369285f1423d48b6ee602030919465e0 Mon Sep 17 00:00:00 2001 From: Dwight Lyle Date: Wed, 13 Dec 2023 17:25:13 -0700 Subject: [PATCH 06/11] Update release notes --- src/content/chainlink-functions/resources/release-notes.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/chainlink-functions/resources/release-notes.mdx b/src/content/chainlink-functions/resources/release-notes.mdx index b815a28fa22..33336be691f 100644 --- a/src/content/chainlink-functions/resources/release-notes.mdx +++ b/src/content/chainlink-functions/resources/release-notes.mdx @@ -6,7 +6,7 @@ title: "Chainlink Functions Release Notes" import { Aside } from "@components" -## Module import support on testnets - 2023-10-07 +## Module import support on testnets - 2023-12-15 You can use module imports with Chainlink Functions source code on testnet networks. See the [Using Imports with Functions](/chainlink-functions/tutorials/importing-packages) tutorial to see and example of how to import and use imported modules with your Functions source code. This feature requires the [Functions Toolkit NPM package](https://www.npmjs.com/package/@chainlink/functions-toolkit/v/0.2.7) `v0.2.7` or later. From f728a10fffef611317be003e46a4614b26df289b Mon Sep 17 00:00:00 2001 From: aelmanaa Date: Thu, 14 Dec 2023 12:35:55 +0100 Subject: [PATCH 07/11] small fixes --- src/config/sidebar.ts | 4 ++ .../resources/release-notes.mdx | 2 +- .../tutorials/api-custom-response.mdx | 4 +- .../tutorials/api-multiple-calls.mdx | 4 +- .../tutorials/api-post-data.mdx | 4 +- .../tutorials/api-query-parameters.mdx | 4 +- .../tutorials/api-use-secrets.mdx | 4 +- .../tutorials/importing-packages.mdx | 39 +++++++++++++++---- .../chainlink-functions/tutorials/index.mdx | 1 + .../common/ChainlinkFunctions.astro | 5 +++ .../common/DenoImportNotes.mdx | 6 +++ 11 files changed, 63 insertions(+), 14 deletions(-) create mode 100644 src/features/chainlink-functions/common/DenoImportNotes.mdx diff --git a/src/config/sidebar.ts b/src/config/sidebar.ts index 4cc1810e3f9..e4014117234 100644 --- a/src/config/sidebar.ts +++ b/src/config/sidebar.ts @@ -542,6 +542,10 @@ export const SIDEBAR: Partial> = { title: "Automate your Functions (Custom Logic Automation)", url: "chainlink-functions/tutorials/automate-functions-custom-logic", }, + { + title: "Using Imports with Functions", + url: "chainlink-functions/tutorials/importing-packages", + }, ], }, { diff --git a/src/content/chainlink-functions/resources/release-notes.mdx b/src/content/chainlink-functions/resources/release-notes.mdx index 33336be691f..61b423ce4e0 100644 --- a/src/content/chainlink-functions/resources/release-notes.mdx +++ b/src/content/chainlink-functions/resources/release-notes.mdx @@ -8,7 +8,7 @@ import { Aside } from "@components" ## Module import support on testnets - 2023-12-15 -You can use module imports with Chainlink Functions source code on testnet networks. See the [Using Imports with Functions](/chainlink-functions/tutorials/importing-packages) tutorial to see and example of how to import and use imported modules with your Functions source code. This feature requires the [Functions Toolkit NPM package](https://www.npmjs.com/package/@chainlink/functions-toolkit/v/0.2.7) `v0.2.7` or later. +You can use module imports with Chainlink Functions source code on testnet networks. See the [Using Imports with Functions](/chainlink-functions/tutorials/importing-packages) tutorial to see an example of how to import and use imported modules with your Functions source code. This feature requires the [Functions Toolkit NPM package](https://www.npmjs.com/package/@chainlink/functions-toolkit/v/0.2.7) `v0.2.7` or later. This feature is available only on testnets. Modules will not import or execute on Functions requests for mainnet networks at this time. diff --git a/src/content/chainlink-functions/tutorials/api-custom-response.mdx b/src/content/chainlink-functions/tutorials/api-custom-response.mdx index 5ce2e0d500f..1dd11d46ee8 100644 --- a/src/content/chainlink-functions/tutorials/api-custom-response.mdx +++ b/src/content/chainlink-functions/tutorials/api-custom-response.mdx @@ -108,7 +108,9 @@ To run the example: #### source.js -The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/3-custom-response/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: Functions requests with custom source code can use vanilla [Deno](https://deno.land/) but cannot use any require statements. Import statements and imported modules are supported only on testnets. +The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/3-custom-response/source.js). The code is self-explanatory and has comments to help you understand all the steps. + + This JavaScript source code uses [Functions.makeHttpRequest](/chainlink-functions/api-reference/javascript-source#http-requests) to make HTTP requests. To request the `ETH/USD` price, the source code calls the `https://min-api.cryptocompare.com/data/pricemultifull?fsyms=ETH&tsyms=USD` URL. If you read the [Functions.makeHttpRequest](/chainlink-functions/api-reference/javascript-source#http-requests) documentation, you see that you must provide the following parameters: diff --git a/src/content/chainlink-functions/tutorials/api-multiple-calls.mdx b/src/content/chainlink-functions/tutorials/api-multiple-calls.mdx index a15365b2c18..fe6ca1fdba8 100644 --- a/src/content/chainlink-functions/tutorials/api-multiple-calls.mdx +++ b/src/content/chainlink-functions/tutorials/api-multiple-calls.mdx @@ -127,7 +127,9 @@ To run the example: #### source.js -The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/8-multiple-apis/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: Functions requests with custom source code can use vanilla [Deno](https://deno.land/) but cannot use any require statements. Import statements and imported modules are supported only on testnets. +The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/8-multiple-apis/source.js). The code is self-explanatory and has comments to help you understand all the steps. + + This JavaScript source code uses [Functions.makeHttpRequest](/chainlink-functions/api-reference/javascript-source#http-requests) to make HTTP requests. The source code fetches the BTC/USD price from different data sources: `https://pro-api.coinmarketcap.com/v1/cryptocurrency/quotes/latest/`, `https://api.coingecko.com/api/v3/simple/price`, and `https://api.coinpaprika.com/v1/tickers/btc-bitcoin` and then calculate the median price. you can read the API docs of [CoinMarketCap](https://coinmarketcap.com/api/documentation/v1/), [CoinGecko](https://www.coingecko.com/en/api/documentation), and [CoinPaprika](https://api.coinpaprika.com/) for details. diff --git a/src/content/chainlink-functions/tutorials/api-post-data.mdx b/src/content/chainlink-functions/tutorials/api-post-data.mdx index 910a140f54a..2b66e952b67 100644 --- a/src/content/chainlink-functions/tutorials/api-post-data.mdx +++ b/src/content/chainlink-functions/tutorials/api-post-data.mdx @@ -117,7 +117,9 @@ To run the example: #### source.js -The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/4-post-data/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: Functions requests with custom source code can use vanilla [Deno](https://deno.land/) but cannot use any require statements. Import statements and imported modules are supported only on testnets. +The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/4-post-data/source.js). The code is self-explanatory and has comments to help you understand all the steps. + + This JavaScript source code uses [Functions.makeHttpRequest](/chainlink-functions/api-reference/javascript-source#http-requests) to make HTTP requests. To request the `JP` country information, the source code calls the `https://countries.trevorblades.com/` URL and provides the query data in the HTTP request body. If you read the [Functions.makeHttpRequest](/chainlink-functions/api-reference/javascript-source#http-requests) documentation, you see that you must provide the following parameters: diff --git a/src/content/chainlink-functions/tutorials/api-query-parameters.mdx b/src/content/chainlink-functions/tutorials/api-query-parameters.mdx index 7798b401fcf..1b14ebbe8f6 100644 --- a/src/content/chainlink-functions/tutorials/api-query-parameters.mdx +++ b/src/content/chainlink-functions/tutorials/api-query-parameters.mdx @@ -101,7 +101,9 @@ To run the example: #### source.js -The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/2-call-api/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: Functions requests with custom source code can use vanilla [Deno](https://deno.land/) but cannot use any require statements. Import statements and imported modules are supported only on testnets. +The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/2-call-api/source.js). The code is self-explanatory and has comments to help you understand all the steps. + + This JavaScript source code uses [Functions.makeHttpRequest](/chainlink-functions/api-reference/javascript-source#http-requests) to make HTTP requests. To request the `ETH/USD` price, the source code calls the `https://min-api.cryptocompare.com/data/pricemultifull?fsyms=ETH&tsyms=USD` URL. If you read the [Functions.makeHttpRequest](/chainlink-functions/api-reference/javascript-source#http-requests) documentation, you see that you must provide the following parameters: diff --git a/src/content/chainlink-functions/tutorials/api-use-secrets.mdx b/src/content/chainlink-functions/tutorials/api-use-secrets.mdx index 173fb3946cf..63247e3e340 100644 --- a/src/content/chainlink-functions/tutorials/api-use-secrets.mdx +++ b/src/content/chainlink-functions/tutorials/api-use-secrets.mdx @@ -122,7 +122,9 @@ To run the example: #### source.js -The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/5-use-secrets-threshold/source.js). The code is self-explanatory and has comments to help you understand all the steps. **Note**: Functions requests with custom source code can use vanilla [Deno](https://deno.land/) but cannot use any require statements. Import statements and imported modules are supported only on testnets. +The Decentralized Oracle Network will run the [JavaScript code](https://github.com/smartcontractkit/smart-contract-examples/blob/main/functions-examples/examples/5-use-secrets-threshold/source.js). The code is self-explanatory and has comments to help you understand all the steps. + + This JavaScript source code uses [Functions.makeHttpRequest](/chainlink-functions/api-reference/javascript-source#http-requests) to make HTTP requests. To request the `BTC` asset price, the source code calls the `https://pro-api.coinmarketcap.com/v1/cryptocurrency/quotes/latest/` URL. If you read the [Functions.makeHttpRequest](/chainlink-functions/api-reference/javascript-source#http-requests) documentation, you see that you must provide the following parameters: diff --git a/src/content/chainlink-functions/tutorials/importing-packages.mdx b/src/content/chainlink-functions/tutorials/importing-packages.mdx index f7b3ffe4cf6..616d7d230bb 100644 --- a/src/content/chainlink-functions/tutorials/importing-packages.mdx +++ b/src/content/chainlink-functions/tutorials/importing-packages.mdx @@ -21,10 +21,31 @@ This tutorial demonstrates how to import modules and use them with your Function - Up to 20 imports total are supported. - Deno supports [ESM compatible NPM imports](https://docs.deno.com/runtime/manual/node/npm_specifiers) and some [standard Node modules](https://docs.deno.com/runtime/manual/node/node_specifiers). See the [Compatability List](https://docs.deno.com/runtime/manual/node/compatibility) for details. - Third-party modules are imported at runtime, so import statements must use asynchronous logic like the following examples: - - Importing from `deno.land`: `const { escape } = await import("https://deno.land/std/regexp/mod.ts");` - - ESM-compatible packages: `const { format } = await import("npm:date-fns");` - - Standard Node modules: `const path = await import("node:path");` - - CDN imports: `const lodash = await import("http://cdn.skypack.dev/lodash");` + + - Importing from `deno.land`: + + ```javascript + const { escape } = await import("https://deno.land/std/regexp/mod.ts") + ``` + + - ESM-compatible packages: + + ```javascript + const { format } = await import("npm:date-fns") + ``` + + - Standard Node modules: + + ```javascript + const path = await import("node:path") + ``` + + - CDN imports: + + ```javascript + const lodash = await import("http://cdn.skypack.dev/lodash") + ``` + - Imported modules abide by all sandbox restrictions and do not have access to the file system, environment variables, or any other Deno permissions.