From 696bc48d9715b17ac54261abbc70de7b7a4bec22 Mon Sep 17 00:00:00 2001 From: Rastislav Date: Thu, 16 May 2024 16:24:44 +0200 Subject: [PATCH] Fixes --- docs/reference/cheatcodes/record.md | 2 +- docs/reference/cheatcodes/start-prank.md | 2 +- ...state.md => start-state-diff-recording.md} | 0 docs/reference/spark-std/bound.md | 2 +- docs/reference/spark/evm-options.md | 32 ++++---- docs/reference/spark/spark-verify-contract.md | 74 +++++++++---------- docs/spark/fork-testing.md | 2 +- docs/spark/spark-std.md | 2 +- docs/spark/writing-tests.md | 4 +- docs/tutorials/best-practices.md | 31 ++++---- docs/tutorials/foxar-docker.md | 6 +- .../invariant-testing-bonding-curve.md | 2 +- docs/tutorials/solmate-nft.md | 2 +- docusaurus.config.ts | 6 +- sidebars.ts | 2 +- 15 files changed, 84 insertions(+), 85 deletions(-) rename docs/reference/cheatcodes/{start-state.md => start-state-diff-recording.md} (100%) diff --git a/docs/reference/cheatcodes/record.md b/docs/reference/cheatcodes/record.md index 02721a5..eea6f47 100644 --- a/docs/reference/cheatcodes/record.md +++ b/docs/reference/cheatcodes/record.md @@ -36,4 +36,4 @@ emit log_uint(uint256(reads[0])); // 1 Spark Standard Library -[Std Storage](../reference/spark-std/std-storage.md) +[Std Storage](../spark-std/std-storage.md) diff --git a/docs/reference/cheatcodes/start-prank.md b/docs/reference/cheatcodes/start-prank.md index d8f1242..0a8a8d9 100644 --- a/docs/reference/cheatcodes/start-prank.md +++ b/docs/reference/cheatcodes/start-prank.md @@ -22,4 +22,4 @@ If the alternative signature of `startPrank` is used, then `tx.origin` is set as Spark Standard Library -[`startHoax`](../reference/spark-std/startHoax.md), [`changePrank`](../reference/spark-std/change-prank.md) +[`startHoax`](../spark-std/startHoax.md), [`changePrank`](../spark-std/change-prank.md) diff --git a/docs/reference/cheatcodes/start-state.md b/docs/reference/cheatcodes/start-state-diff-recording.md similarity index 100% rename from docs/reference/cheatcodes/start-state.md rename to docs/reference/cheatcodes/start-state-diff-recording.md diff --git a/docs/reference/spark-std/bound.md b/docs/reference/spark-std/bound.md index 88258c6..5050454 100644 --- a/docs/reference/spark-std/bound.md +++ b/docs/reference/spark-std/bound.md @@ -12,7 +12,7 @@ function bound(uint256 x, uint256 min, uint256 max) public returns (uint256 resu A mathematical function for wrapping inputs of fuzz tests into a certain range. -You can use it instead of the `assume` cheatcode to get better performance in some cases. Read more [here](../../cheatcodes/assume.md). +You can use it instead of the `assume` cheatcode to get better performance in some cases. Read more [here](../cheatcodes/assume.md). ### Examples diff --git a/docs/reference/spark/evm-options.md b/docs/reference/spark/evm-options.md index b6801d2..83bd970 100644 --- a/docs/reference/spark/evm-options.md +++ b/docs/reference/spark/evm-options.md @@ -1,43 +1,43 @@ #### EVM Options -`-f` *url* -`--rpc-url` *url* -`--fork-url` *url* +`-f` *url* +`--rpc-url` *url* +`--fork-url` *url*     Fetch state over a remote endpoint instead of starting from an empty state.     If you want to fetch state from a specific block number, see `--fork-block-number`. -`--fork-block-number` *block* +`--fork-block-number` *block*     Fetch state from a specific block number over a remote endpoint. See `--fork-url`. -`--fork-retry-backoff ` +`--fork-retry-backoff `      Initial retry backoff on encountering errors. -`--no-storage-caching` +`--no-storage-caching`     Explicitly disables the use of RPC caching.     All storage slots are read entirely from the endpoint. See `--fork-url`. -`-v` -`--verbosity` +`-v` +`--verbosity`     Verbosity of the EVM.     Pass multiple times to increase the verbosity (e.g. `-v`, `-vv`, `-vvv`). -    Verbosity levels: -    - 2: Print logs for all tests -    - 3: Print execution traces for failing tests -    - 4: Print execution traces for all tests, and setup traces for failing tests +    Verbosity levels: +    - 2: Print logs for all tests +    - 3: Print execution traces for failing tests +    - 4: Print execution traces for all tests, and setup traces for failing tests     - 5: Print execution and setup traces for all tests -`--sender` *address* +`--sender` *address*     The address which will be executing tests -`--initial-balance` *balance* +`--initial-balance` *balance*     The initial balance of deployed contracts -`--ffi` +`--ffi`     Enables the [FFI cheatcode][ffi-cheatcode] -[ffi-cheatcode]: ../../cheatcodes/ffi.md +[ffi-cheatcode]: ../cheatcodes/ffi.md diff --git a/docs/reference/spark/spark-verify-contract.md b/docs/reference/spark/spark-verify-contract.md index 8876793..5ab2ea9 100644 --- a/docs/reference/spark/spark-verify-contract.md +++ b/docs/reference/spark/spark-verify-contract.md @@ -21,7 +21,7 @@ You must provide: In case of Etherscan verification, you must also provide: - Your Etherscan API key, either by passing it as an argument or setting `ETHERSCAN_API_KEY` -To find the exact compiler version, run `~/.svm/x.y.z/solc-x.y.z --version` and search for the 8 hex digits in the version string [here](https://etherscan.io/solcversions). +To find the exact compiler version, run `~/.svm/x.y.z/solc-x.y.z --version` and search for the 8 hex digits in the version string. The path to the contract is in the format `:`, e.g. `src/Contract.sol:Contract`. @@ -31,101 +31,101 @@ This command will try to compile the source code of the flattened contract if `- You can specify **ABI-encoded** constructor arguments with `--constructor-args`. Alternatively, you can specify a file containing **space-separated** constructor arguments with `--constructor-args-path`. -(Note that [cache](../config/project.html#cache) must be enabled in the config for the latter to work.) +(Note that [cache](../config/project.md#cache) must be enabled in the config for the latter to work.) ### OPTIONS #### Verify Contract Options -`--verifier` _name_ +`--verifier` _name_     The verification provider. Available options: `etherscan`, `sourcify` & `blockscout`. Default: `etherscan`. Note: make sure you add "/api\?" to the end of the Blockscout homepage explorer URL. -`--verifier-url` _url_ -    The optional verifier url for submitting the verification request. +`--verifier-url` _url_ +    The optional verifier url for submitting the verification request.     Environment: `VERIFIER_URL` -`--compiler-version` _version_ +`--compiler-version` _version_     The compiler version used to build the smart contract.     To find the exact compiler version, run `~/.svm/x.y.z/solc-x.y.z --version` where `x` and -`y` are major and minor version numbers respectively, then search for the 8 hex digits in the version string [here](https://etherscan.io/solcversions). +`y` are major and minor version numbers respectively, then search for the 8 hex digits in the version string. -`--num-of-optimizations` _num_ -`--optimizer-runs` _num_ +`--num-of-optimizations` _num_ +`--optimizer-runs` _num_     The number of optimization runs used to build the smart contract. -`--constructor-args` _args_ +`--constructor-args` _args_     The ABI-encoded constructor arguments. Conflicts with `--constructor-args-path`. -`--constructor-args-path` _file_ +`--constructor-args-path` _file_     The path to a file containing the constructor arguments. Conflicts with `--constructor-args`. -`--chain-id` _chain_ -`--chain` _chain_ -    The ID or name of the chain the contract is deployed to. +`--chain-id` _chain_ +`--chain` _chain_ +    The ID or name of the chain the contract is deployed to.     Default: mainnet -`--flatten` +`--flatten`     Flag indicating whether to flatten the source code before verifying.     If this flag is not provided, the JSON standard input will be used instead. -`-f` -`--force` +`-f` +`--force`     Do not compile the flattened smart contract before verifying. -`--delay` _delay_ +`--delay` _delay_     Optional timeout to apply in between attempts in seconds. Defaults to 3. -`--retries` _retries_ +`--retries` _retries_     Number of attempts for retrying. Defaults to 15. -`--show-standard-json-input` +`--show-standard-json-input`     Command outputs JSON suitable for saving to a file and uploading to block explorers for verification. -`--watch` -    Wait for verification result after submission. +`--watch` +    Wait for verification result after submission.     Automatically runs `spark verify-check` until the verification either fails or succeeds. #### Project Options -`--build-info` +`--build-info`     Generate build info files. -`--build-info-path` _path_ +`--build-info-path` _path_     Output path to directory that build info files will be written to. -`--root` _path_ +`--root` _path_     The project's root path. By default, this is the root directory of the current git repository, or the current working directory. -`-C` _path_ -`--contracts` _path_ -    The contracts source directory. +`-C` _path_ +`--contracts` _path_ +    The contracts source directory.     Environment: `DAPP_SRC` -`--lib-paths` _path_ +`--lib-paths` _path_     The path to the library folder. -`-R` _remappings_ -`--remappings` _remappings_ +`-R` _remappings_ +`--remappings` _remappings_     The project's remappings.     The parameter is a comma-separated list of remappings in the format `=`. -`--cache-path` _path_ +`--cache-path` _path_     The path to the compiler cache. -`--config-path` _file_ +`--config-path` _file_     Path to the config file. -`--hh` -`--hardhat` +`--hh` +`--hardhat`     This is a convenience flag, and is the same as passing `--contracts contracts --lib-paths node-modules`. #### Common Options -`-h` -`--help` +`-h` +`--help`     Prints help information. ### EXAMPLES diff --git a/docs/spark/fork-testing.md b/docs/spark/fork-testing.md index 14ab712..ee9424b 100644 --- a/docs/spark/fork-testing.md +++ b/docs/spark/fork-testing.md @@ -5,7 +5,7 @@ title: Fork Testing Spark supports testing in a forked environment with two different approaches: - [**Forking Mode**](#forking-mode) — use a single fork for all your tests via the `spark test --fork-url` flag -- [**Forking Cheatcodes**](#forking-cheatcodes) — create, select, and manage multiple forks directly in Solidity test code via [forking cheatcodes](../cheatcodes/forking) +- [**Forking Cheatcodes**](#forking-cheatcodes) — create, select, and manage multiple forks directly in Solidity test code via [forking cheatcodes](../reference/cheatcodes/forking.md) Which approach to use? Forking mode affords running an entire test suite against a specific forked environment, while forking cheatcodes provide more flexibility and expressiveness to work with multiple forks in your tests. Your particular use case and testing strategy will help inform which approach to use. diff --git a/docs/spark/spark-std.md b/docs/spark/spark-std.md index 07702cf..6a2d32d 100644 --- a/docs/spark/spark-std.md +++ b/docs/spark/spark-std.md @@ -117,4 +117,4 @@ uint256 ten = stdMath.abs(-10) > 📚 **Reference** > -> See the [Spark Standard Library Reference](../reference/spark-std/) for a complete overview of Spark Standard Library. +> See the Spark Standard Library Reference for a complete overview of Spark Standard Library. diff --git a/docs/spark/writing-tests.md b/docs/spark/writing-tests.md index 986c93b..3e54232 100644 --- a/docs/spark/writing-tests.md +++ b/docs/spark/writing-tests.md @@ -67,7 +67,7 @@ Spark uses the following keywords in tests: } ``` -A good practice is to use the pattern `test_Revert[If|When]_Condition` in combination with the [`expectRevert`](../cheatcodes/expect-revert.md) cheatcode (cheatcodes are explained in greater detail in the following [section](./cheatcodes.md)). Also, other testing practices can be found in the [Tutorials section](../tutorials/best-practices.md). +A good practice is to use the pattern `test_Revert[If|When]_Condition` in combination with the [`expectRevert`](../reference/cheatcodes/expect-revert.md) cheatcode (cheatcodes are explained in greater detail in the following [section](./cheatcodes.md)). Also, other testing practices can be found in the [Tutorials section](../tutorials/best-practices.md). Now, instead of using `testFail`, you know exactly what reverted and with which error: @@ -120,4 +120,4 @@ contract MyOtherContractTest is Test, HelperContract { > 💡 **Tip** > -> Use the [`getCode`](../cheatcodes/get-code.md) cheatcode to deploy contracts with incompatible Solidity versions. +> Use the [`getCode`](../reference/cheatcodes/get-code.md) cheatcode to deploy contracts with incompatible Solidity versions. diff --git a/docs/tutorials/best-practices.md b/docs/tutorials/best-practices.md index f9183f2..a23729d 100644 --- a/docs/tutorials/best-practices.md +++ b/docs/tutorials/best-practices.md @@ -5,21 +5,20 @@ title: Best Practices This guide documents the suggested best practices when developing with Foxar. In general, it's recommended to handle as much as possible with [`spark fmt`](../reference/config/formatter), and anything this doesn't handle is below. -- [Best Practices](#best-practices) - - [General Contract Guidance](#general-contract-guidance) - - [Tests](#tests) - - [General Test Guidance](#general-test-guidance) - - [Fork Tests](#fork-tests) - - [Test Harnesses](#test-harnesses) - - [Internal Functions](#internal-functions) - - [Private Functions](#private-functions) - - [Workaround Functions](#workaround-functions) - - [Best practices](#best-practices-1) - - [Taint Analysis](#taint-analysis) - - [Scripts](#scripts) - - [Private Key Management](#private-key-management) - - [Comments](#comments) - - [Resources](#resources) +- [General Contract Guidance](#general-contract-guidance) +- [Tests](#tests) + - [General Test Guidance](#general-test-guidance) + - [Fork Tests](#fork-tests) + - [Test Harnesses](#test-harnesses) + - [Internal Functions](#internal-functions) + - [Private Functions](#private-functions) + - [Workaround Functions](#workaround-functions) + - [Best practices](#best-practices) + - [Taint Analysis](#taint-analysis) +- [Scripts](#scripts) + - [Private Key Management](#private-key-management) +- [Comments](#comments) +- [Resources](#resources) ## General Contract Guidance @@ -116,7 +115,7 @@ Additional best practices from [samsczun](https://twitter.com/samczsun)'s [How D 1. Be careful with fuzz tests on a fork to avoid burning through RPC requests with non-deterministic fuzzing. If the input to your fork fuzz test is some parameter which is used in an RPC call to fetch data (e.g. querying the token balance of an address), each run of a fuzz test uses at least 1 RPC request, so you'll quickly hit rate limits or usage limits. Solutions to consider: - Replace multiple RPC calls with a single [multicall](https://github.com/mds1/multicall). - - Specify a fuzz/invariant [seed](/src/reference/config/testing#seed): this makes sure each `spark test` invocation uses the same fuzz inputs. RPC results are cached locally, so you'll only query the node the first time. + - Specify a fuzz/invariant [seed](../reference/config/testing.md#seed): this makes sure each `spark test` invocation uses the same fuzz inputs. RPC results are cached locally, so you'll only query the node the first time. - In CI, consider setting the fuzz seed using a [computed environment variable](https://github.com/sablier-labs/v2-core/blob/d1157b49ed4bceeff0c4e437c9f723e88c134d3a/.github/workflows/ci.yml#L252-L254) so it changes every day or every week. This gives flexibility on the tradeoff between increasing randomness to find more bugs vs. using a seed to reduce RPC requests. - Structure your tests so the data you are fuzzing over is computed locally by your contract, and not data that is used in an RPC call (may or may not be feasible based on what you're doing). - Lastly, you can of course always run a local node or bump your RPC plan. diff --git a/docs/tutorials/foxar-docker.md b/docs/tutorials/foxar-docker.md index c74d49c..fe0ca0d 100644 --- a/docs/tutorials/foxar-docker.md +++ b/docs/tutorials/foxar-docker.md @@ -11,12 +11,12 @@ This tutorial shows you how to build, test, and deploy a smart contract using Fo ### Installation and Setup The only installation required to run this tutorial is Docker, and optionally, an IDE of your choice. -Follow the [Docker installation instructions](/getting-started/installation.html#using-with-docker). +Follow the [Docker installation instructions](../getting-started/installation.md#using-with-docker). -To keep future commands succinct, let's re-tag the image: +To keep future commands succinct, let's re-tag the image: `docker tag ghcr.io/foxar-rs/foxar:latest foxar:latest` -Having Foxar installed locally is not strictly required, but it may be helpful for debugging. You can install it using [foxarup](/getting-started/installation.html#using-foxarup). +Having Foxar installed locally is not strictly required, but it may be helpful for debugging. You can install it using [foxarup](../getting-started/installation.md#using-foxarup). Finally, to use any of the `probe` or `spark create` portions of this tutorial, you will need access to an Ethereum node. If you don't have your own node running (likely), you can use a 3rd party node service. We won't recommend a specific provider in this tutorial. A good place to start learning about Nodes-as-a-Service is [Ethereum's article](https://ethereum.org/en/developers/docs/nodes-and-clients/nodes-as-a-service/) on the subject. diff --git a/docs/tutorials/invariant-testing-bonding-curve.md b/docs/tutorials/invariant-testing-bonding-curve.md index bc9cca4..d7fd19d 100644 --- a/docs/tutorials/invariant-testing-bonding-curve.md +++ b/docs/tutorials/invariant-testing-bonding-curve.md @@ -8,7 +8,7 @@ This tutorial will cover invariant testing, using **Bonding Curve Implementation However, this guide is for educational purposes only. The code is not audited. Please do not use it in production. -> 💡 Note: A full implementation of the bonding curve can be found [here](https://github.com/Ratimon/bonding-curves), and for further reading about invariant testing, we can check out the `Invariant Testing` [reference](../reference/spark/invariant-testing.md). +> 💡 Note: A full implementation of the bonding curve can be found [here](https://github.com/Ratimon/bonding-curves), and for further reading about invariant testing, we can check out the `Invariant Testing` [reference](../spark/invariant-testing.md). ### Quick Start diff --git a/docs/tutorials/solmate-nft.md b/docs/tutorials/solmate-nft.md index ce14feb..3c57311 100644 --- a/docs/tutorials/solmate-nft.md +++ b/docs/tutorials/solmate-nft.md @@ -8,7 +8,7 @@ This tutorial will walk you through creating an OpenSea compatible NFT with Foxa ### Create project and install dependencies -Start by setting up a Foxar project following the steps outlined in the [Getting started section](../getting-started/installation.html). We will also install Solmate for their ERC721 implementation, as well as some OpenZeppelin utility libraries. Install the dependencies by running the following commands from the root of your project: +Start by setting up a Foxar project following the steps outlined in the [Getting started section](../getting-started/installation.md). We will also install Solmate for their ERC721 implementation, as well as some OpenZeppelin utility libraries. Install the dependencies by running the following commands from the root of your project: ```bash spark install transmissions11/solmate Openzeppelin/openzeppelin-contracts diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 5146035..f93618b 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -41,15 +41,15 @@ function getNextVersionName() { const config: Config = { title: "Foxar", tagline: "Foxar", - favicon: "img/Brand_Mark_2@3x.png", + favicon: "img/favicon.png", url: "https://foxar.dev", baseUrl, organizationName: "bchainhub", projectName: "foxar-docs", - onBrokenLinks: "throw", - onBrokenAnchors: "throw", + onBrokenLinks: "warn", + onBrokenAnchors: "warn", onBrokenMarkdownLinks: "warn", i18n: { diff --git a/sidebars.ts b/sidebars.ts index 547c39d..d5531ef 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -800,7 +800,7 @@ const sidebars: SidebarsConfig = { "reference/cheatcodes/pause-gas-metering", "reference/cheatcodes/resume-gas-metering", "reference/cheatcodes/tx-gas-price", - "reference/cheatcodes/start-state", + "reference/cheatcodes/start-state-diff-recording", "reference/cheatcodes/stop-and-return-state-diff", ], },