diff --git a/src/SUMMARY.md b/src/SUMMARY.md
index e67f33757..5ca011e1e 100644
--- a/src/SUMMARY.md
+++ b/src/SUMMARY.md
@@ -7,6 +7,15 @@
- [Installation](./getting-started/installation.md)
- [First Steps with Foundry](./getting-started/first-steps.md)
+# Migrating to V1
+
+- [Introduction](./migrating-to-v1/migrating-to-v1.md)
+- [Upgrading to V1](./migrating-to-v1/upgrading-to-v1.md)
+- [Deprecated Features](./migrating-to-v1/deprecated-features.md)
+- [V1 Changes](./migrating-to-v1/v1-changes.md)
+ - [Non-breaking Changes](./migrating-to-v1/non-breaking-changes.md)
+ - [Breaking Changes](./migrating-to-v1/breaking-changes.md)
+
# Projects
- [Creating a New Project](./projects/creating-a-new-project.md)
diff --git a/src/migrating-to-v1/breaking-changes.md b/src/migrating-to-v1/breaking-changes.md
new file mode 100644
index 000000000..392d669aa
--- /dev/null
+++ b/src/migrating-to-v1/breaking-changes.md
@@ -0,0 +1,342 @@
+## Breaking changes
+
+### Table of contents
+1. [Introduction](#introduction)
+2. [`expectEmit`](#expectemit)
+3. [`expectCall`](#expectcall)
+4. [`expectRevert`](#expectrevert)
+5. [Testing internal or library calls with the new changes](#testing-internal-calls-or-libraries-with-expectcall-expectrevert-and-expectemit)
+
+### Introduction
+
+When it comes to breaking changes, there has been a slight rework for the assertion (`expect*`) cheatcodes that removes previously allowed unintended or confusing behavior.
+
+The biggest change is that these cheatcodes will now work only for the next call, not at the "test" level anymore. The philosophy behind this is that by making these cheatcodes more strict through this requirement, tests will be more accurate as the cheatcodes will now only succeed under more strict conditions.
+
+#### `expectEmit`
+
+`expectEmit` previously allowed you to assert that a log was emitted during the execution of the test. With v1, the following changes have been made:
+
+- It now only works for the _next call_. This means if you used to declare all your expected emits at the top of the test, you may now have to move them to just before the next call you perform. Cheatcode calls are ignored. As long as the events are emitted during the next call's execution, they will be matched.
+- The events have to be _ordered_. That means, if you're trying to match events [A, B, C], you must declare them in this order.
+ - Skipping events is possible. Therefore, if a function emits events [A, B, C, D, E] and you want to match [B, D, E], you just need to declare them in that order.
+
+To illustrate, see the following examples:
+
+```solidity
+
+contract Emitter {
+ event A(uint256 indexed a);
+ event B(uint256 b);
+ event C(uint256 c1, uint256 c2);
+ event D(bytes32 d1, uint256 f2, address indexed d3);
+ event E(uint256 indexed e);
+
+ /// emit() emits events [A, B, C, D, E]
+ function emitEvent() external {
+ emit A(1);
+ emit B(2);
+ emit C(3, 3);
+ emit D(bytes32("gm"), 4, address(0xc4f3));
+ emit E(5);
+ }
+}
+
+contract EmitTest is Test {
+ Emitter public emitter;
+
+ event A(uint256 indexed a);
+ event B(uint256 b);
+ event C(uint256 c1, uint256 c2);
+ event D(bytes32 d1, uint256 f2, address indexed d3);
+ event E(uint256 indexed e);
+
+ function setUp() public {
+ emitter = new Emitter();
+ }
+
+ // CORRECT BEHAVIOR: Declare all your expectEmits just before the next call,
+ // on the test.
+ // emitEvent() emits [A, B, C, D, E], and we're expecting [A, B, C, D, E].
+ // This passes.
+ function testExpectEmit() public {
+ // A quick refresher on `vm.expectEmit` params:
+ // The first three booleans indicate if you want to check `topic1`, `topic2` and `topic3`.
+ // `topic0` is always checked.
+ // The last boolean indicates if you want to check the data.
+ // If you want to read further, you can go to the `vm.expectEmit` reference: https://book.getfoundry.sh/cheatcodes/expect-emit?highlight=expectEmit#expectemit
+ vm.expectEmit(true, false, false, true);
+ emit A(1);
+ vm.expectEmit(false, false, false, true);
+ emit B(2);
+ vm.expectEmit(false, false, false, true);
+ emit C(3, 3);
+ // It's also possible to skip all parameters entirely and just call the cheatcode.
+ vm.expectEmit();
+ emit D(bytes32("gm"), 4, address(0xc4f3));
+ vm.expectEmit();
+ emit E(5);
+ emitter.emitEvent();
+ }
+
+ // CORRECT BEHAVIOR: Declare all your expectEmits just before the next call,
+ // on the test.
+ // emitEvent() emits [A, B, C, D, E], and we're expecting [B, D, E].
+ // This passes.
+ function testExpectEmitWindow() public {
+ vm.expectEmit();
+ emit B(2);
+ vm.expectEmit();
+ emit D(bytes32("gm"), 4, address(0xc4f3));
+ vm.expectEmit();
+ emit E(5);
+ emitter.emitEvent();
+ }
+
+ // INCORRECT BEHAVIOR: Declare all your expectEmits in the wrong order.
+ // emitEvent() emits [A, B, C, D, E], and we're expecting [D, B, E].
+ // This fails, as D is emitted after B, not before.
+ function testExpectEmitWindowFailure() public {
+ vm.expectEmit();
+ emit D(bytes32("gm"), 4, address(0xc4f3));
+ vm.expectEmit();
+ emit B(2);
+ vm.expectEmit();
+ emit E(5);
+ emitter.emitEvent();
+ }
+
+ // CORRECT BEHAVIOR: Declare all your expectEmits in an internal function.
+ // Calling a contract function internally is a JUMP, not a call,
+ // therefore it's a valid pattern, useful if you have a lot of events to expect.
+ // emitEvent() emits [A, B, C, D, E], and we're expecting [B, D, E].
+ // This passes.
+ function testExpectEmitWithInternalFunction() public {
+ declareExpectedEvents();
+ emitter.emitEvent();
+ }
+
+ function declareExpectedEvents() internal {
+ vm.expectEmit(true, false, false, true);
+ emit B(2);
+ vm.expectEmit(true, false, false, true);
+ emit D(bytes32("gm"), 4, address(0xc4f3));
+ vm.expectEmit(true, false, false, true);
+ emit E(5);
+ }
+}
+```
+
+As illustrated above, if you'd like to make your tests more brief, you can declare your expected events in an internal function in your test contract to remove visual clutter. This is not an external call, which means they won't count for detecting events.
+
+#### `expectCall`
+
+Just like `expectEmit`, `expectCall` has gotten a similar rework. Before, it worked at the test level, which meant you could declare the calls you expect to see upfront and then start calling external functions. The new behavior is the following one:
+
+- It now only works for the next _call's subcalls_. This means that the call(s) you expect need to happen inside an external call for them to be detected. Calling it at the test level (directly) won't count.
+ - This is explained through "depth": the `expectCall` cheatcode is called at a "test-level" depth, so we enforce that the calls we expect to see are made at a "deeper" depth to be able to count them properly. Depth is increased whenever we make an external call. Internal calls do not increase depth.
+
+To illustrate, see the following examples:
+
+```solidity
+contract Protocol {
+ function doSomething() external {
+ // do something...
+ }
+}
+
+contract Caller {
+ Protocol public protocol;
+
+ function setUp() public {
+ protocol = new Protocol();
+ }
+
+ function foo() public {
+ // do something...
+ }
+
+ function baz() public {
+ // do something...
+ }
+
+ function bar() public {
+ protocol.doSomething();
+ // do something...
+ }
+}
+
+contract ExpectCallTest is Test {
+ Caller public caller;
+
+ function setUp() public {
+ caller = new Caller();
+ }
+
+ // CORRECT BEHAVIOR: We expect a call to `doSomething()` in the next call,
+ // So we declare our expected call, and then call `caller.bar()`, which will
+ // call `protocol.doSomething()` internally.
+ // `doSomething()` is nested inside `bar`, so this passes.
+ function testExpectCall() public {
+ vm.expectCall(caller.protocol.address, abi.encodeCall(Protocol.doSomething, ()));
+ // This will call bar internally, so this is valid.
+ caller.bar();
+ }
+
+ // INCORRECT BEHAVIOR: We expect a call to `doSomething()` in the next call,
+ // So we declare our expected call, and then call `protocol.doSomething()` directly.
+ // `doSomething()` is not nested, but rather called at the test level.
+ // This doesn't satisfy the depth requirement described above,
+ // so this fails.
+ function testExpectCallFailure() public {
+ vm.expectCall(caller.protocol.address, abi.encodeCall(Protocol.doSomething, ()));
+ // We're calling doSomething() directly here.
+ // This is not inside the next call's subcall tree, but rather a test-level
+ // call. This fails.
+ caller.protocol().doSomething();
+ }
+
+ // CORRECT BEHAVIOR: Sometimes, we want to directly expect the call we're gonna
+ // call next, but we need to satisfy the depth requirement. In those cases,
+ // this pattern can be used.
+ // Calling exposed_callFoo using `this` will create a new call context which
+ // will increase depth. In its subcall tree, we'll detect `exposed_callFoo`,
+ // which will make the test pass.
+ // See more info on the best practices section:
+ // https://book.getfoundry.sh/tutorials/best-practices#internal-functions
+ function testExpectCallWithNest() public {
+ vm.expectCall(address(caller), abi.encodeWithSelector(caller.foo.selector));
+ this.exposed_callFoo();
+ }
+
+ function exposed_callFoo() public {
+ caller.foo();
+ }
+}
+```
+
+#### `expectRevert`
+
+`expectRevert` currently allows to expect for reverts at the test-depth level. This means that a revert can be declared at the top of the test, and as long as a function in the test reverts, the test will pass. The new behavior is the following:
+
+- `expectRevert` CANNOT be used with other `expect` cheatcodes. It will fail if it detects they're being used at the same time.
+ - The reasoning for this is that calls that revert are rolled back, and events and calls therefore never happen. This restriction helps model real execution behavior.
+- `expectRevert` now works only for the next call. If the next call does not revert, the cheatcode will fail and therefore the test will also fail. The depth of the revert does not matter: as long as the next call reverts, either immediately or deeper into its call subtree, the cheatcode will succeed.
+
+To illustrate, see the following examples:
+
+```solidity
+
+contract Reverter {
+ function revertWithMessage(string memory message) public pure {
+ require(false, message);
+ }
+
+ function doNotRevert() public {
+ // do something unrelated, do not revert.
+ }
+}
+
+contract ExpectRevertTest is Test {
+ Reverter reverter;
+
+ function setUp() public {
+ reverter = new Reverter();
+ }
+
+ /// CORRECT BEHAVIOR: We expect `revertWithMessage` to revert,
+ /// so we declare a expectRevert and then call the function.
+ function testExpectRevertString() public {
+ vm.expectRevert(bytes("revert"));
+ reverter.revertWithMessage("revert");
+ }
+
+ // INCORRECT BEHAVIOR: We correctly expect that a function will revert in this
+ // test, but we declare the expected revert before the wrong function,
+ // `doNotRevert()`, which does not revert. The cheatcode therefore fails.
+ function testFailRevertNotOnImmediateNextCall() public {
+ // expectRevert should only work for the next call. However,
+ // we do not immediately revert, so this test fails.
+ vm.expectRevert("revert");
+ reverter.doNotRevert();
+ reverter.revertWithMessage("revert");
+ }
+}
+```
+
+### Testing internal calls or libraries with `expectCall`, `expectRevert` and `expectEmit`
+
+With the changes to `expectCall` and `expectRevert`, library maintainers might need to modify tests that expect calls or reverts on library functions that might be marked as internal. As an external call needs to be forced to satisfy the depth requirement, an intermediate contract that exposes an identical API to the function that needs to be called can be used.
+
+See the following example for testing a revert on a library.
+
+```solidity
+library MathLib {
+ function add(uint a, uint b) internal pure returns (uint256) {
+ return a + b;
+ }
+}
+
+library EmitLib {
+ event Log();
+ function emit() internal {
+ emit Log();
+ }
+}
+
+// Intermediate "mock" contract that calls the library function
+// and returns the result.
+contract MathLibMock {
+ function add(uint a, uint b) external returns (uint256) {
+ return MathLib.add(a, b);
+ }
+}
+
+contract EmitLibMock {
+ function log() external {
+ EmitLib.emit();
+ }
+}
+
+contract MathLibTest is Test {
+ MathLibMock public mathMock;
+ EmitLibMock public emitMock;
+
+ event Log();
+
+ function setUp() public {
+ mathMock = new MathLibMock();
+ emitMock = new EmitLibMock();
+ }
+
+ // INCORRECT BEHAVIOR: MathLib.add will revert due to arithmetic errors,
+ // but as the function is marked as internal, it'll be a test level revert
+ // instead of a call revert that expectRevert is supposed to catch.
+ // The test will fail, and the error will let you know that you have a
+ // "dangling" expectRevert.
+ function testRevertOnMathLibWithNoMock() public {
+ vm.expectRevert(stdError.arithmeticError);
+ MathLib.add(type(uint256).max, 1);
+ }
+
+ // CORRECT BEHAVIOR: mock.add will revert due to arithmetic errors,
+ // and it will be successfully detected by the `expectRevert` cheatcode.
+ function testRevertOnMathLibWithMock() public {
+ vm.expectRevert(stdError.arithmeticError);
+ mathMock.add(type(uint256).max, 1);
+ }
+
+ // CORRECT BEHAVIOR: Use the mock contract to expect a call on a lib
+ function testCanCallMathLib() public {
+ vm.expectCall(address(mathMock), abi.encodeWithSelector(mathMock.add.selector, 1, 2));
+ mathMock.add(1, 2);
+ }
+
+ // CORRECT BEHAVIOR: The same pattern applies to `expectRevert`.
+ function testLibraryEmitWithMock() public {
+ vm.expectEmit();
+ emit Log();
+ emitMock.log();
+ }
+}
+```
\ No newline at end of file
diff --git a/src/migrating-to-v1/deprecated-features.md b/src/migrating-to-v1/deprecated-features.md
new file mode 100644
index 000000000..ac2bbc64e
--- /dev/null
+++ b/src/migrating-to-v1/deprecated-features.md
@@ -0,0 +1,67 @@
+## Deprecated features
+
+With Foundry v1, we've started deprecating features that are considered anti-patterns or might be misleading and confusing for developers. Deprecated means that while you can continue using these features, it is now a discouraged practice and you should plan on migrating away from using these.
+
+### Removing the `invariant` prefix
+
+The `invariant` test prefix has now been deprecated, and the new expected prefix is `statefulFuzz`. This is mainly to have more correctness on naming: Invariants can be tested with regular fuzz tests. The difference between Foundry's fuzz and invariant tests is that fuzz tests are *stateless* while invariant tests are *stateful*. This means that now writing tests in this manner is valid:
+
+```solidity
+/// Old, deprecated way of declaring an invariant test
+function invariantTestEq() public {
+ // Assert your invariants
+}
+
+/// New
+function statefulFuzzTestEq() public {
+ // Assert your invariants
+}
+```
+
+### `testFail`
+
+Using `testFail` to write failing tests is now discouraged, because it can introduce footguns in a test. Specifically, it cannot distinguish between revert reasons, and therefore tests may inadvertently pass and this is hard to detect.
+
+A better pattern is to use `expectRevert` to ensure that a function call reverted in a specific way. This way, the test failure is expected explicitly, removing the possibility that the test fails in an unintended, undetectable way.
+
+An example:
+
+```solidity
+
+contract Mock {
+ function revert_() public {
+ revert("This reverts");
+ }
+}
+
+contract TestFailDeprecated is Test {
+ Mock public mock;
+
+ function setUp() public {
+ mock = new Mock();
+ }
+
+ /// Deprecated way.
+ function testFailReverter() public {
+ mock.revert_();
+ }
+
+ // Better way, without using testFail.
+ /// The call to revert_ has been refactored and is now expected to fail
+ /// with expectRevert()
+ function test_revertIf_alwaysReverts() public {
+ vm.expectRevert("This reverts");
+ // Call using `this` to increase depth
+ this.exposed_call_Reverter();
+ }
+
+ function exposed_callReverter() public {
+ mock.revert_();
+ }
+
+}
+```
+
+### Removing cheatcodes support on some precompiles
+
+It is now impossible to use the following cheatcodes on precompiles: `etch`, `load`, `store`, `deal`. The rationale is that utilizing cheatcodes on precompile addresses (0 < n < 9) can cause unexpected behavior and test failures. Prefer using the `makeAddr` cheatcode for creating addresses to use in tests.
\ No newline at end of file
diff --git a/src/migrating-to-v1/migrating-to-v1.md b/src/migrating-to-v1/migrating-to-v1.md
new file mode 100644
index 000000000..2db136b0d
--- /dev/null
+++ b/src/migrating-to-v1/migrating-to-v1.md
@@ -0,0 +1,17 @@
+## Migrating to Foundry v1
+
+Foundry v1 is the blazing-fast smart contract testing framework you already know, but finally marked as stable and respecting [semver](https://semver.org/). It's the culmination of over a year of work and more than 250 contributors that made it happen.
+
+With the v1 release, very few breaking changes have been included, meaning migration should be mostly painless. This guide will help you understand what these changes are and how to handle them properly.
+
+### What to expect
+
+v1 mainly increases the strictness of several cheatcodes, and accommodating this is the primary change required to migrate to v1. We recommend migrating to v1 as soon as possible, as the stricter cheats may reveal bugs or issues in your code and test suite.
+
+If migration is time consuming, you can consider upgrading your local foundry installation while migrating tests, but maintaining nightly usage on CI to avoid any failures that might disrupt your workflow.
+
+Aside from this, v1 is still the same Foundry you know.
+
+### I need support. Where do I go?
+
+The [dev Telegram](https://t.me/foundry_rs) is available for general conversation around Foundry and its features, while the [support Telegram](https://t.me/foundry_support) is available for any concerns you may have that are not covered in this guide.
\ No newline at end of file
diff --git a/src/migrating-to-v1/non-breaking-changes.md b/src/migrating-to-v1/non-breaking-changes.md
new file mode 100644
index 000000000..768308f4e
--- /dev/null
+++ b/src/migrating-to-v1/non-breaking-changes.md
@@ -0,0 +1,6 @@
+## Non-breaking but important changes
+
+- Snapshot failures between fuzz runs [are now persisted](https://github.com/foundry-rs/foundry/pull/4974), so workarounds are not needed anymore when testing fuzz runs that use snapshots.
+- Sensitive broadcast logs are now logged into the `.gitignore`d `cache` directory, instead of being included in the broadcast files that are intended to be committed.
+- The base fee calculation on Anvil is now entirely skipped if the fee is set to 0.
+- `vm.startPrank` now overwrites the existing prank instead of just erroring. However, the already set prank must be used first.
\ No newline at end of file
diff --git a/src/migrating-to-v1/upgrading-to-v1.md b/src/migrating-to-v1/upgrading-to-v1.md
new file mode 100644
index 000000000..dc299a881
--- /dev/null
+++ b/src/migrating-to-v1/upgrading-to-v1.md
@@ -0,0 +1,19 @@
+## Upgrading to Foundry V1
+
+### Local Installation
+
+To upgrade, you'll need to reinstall `foundryup`. To do so, open your terminal and run the following command:
+
+```sh
+curl -L https://foundry.paradigm.xyz | bash
+```
+
+This will reinstall `foundryup`. You can then run `foundryup` on your terminal to download the latest `V1` version.
+
+After this, you're now up to date with the latest stable Foundry version.
+
+### Upgrading your CI
+
+When it comes to CI, you can add a `version` input field with `v1.0.0` or your desired stable release. This will pin the CI to that stable version.
+
+If you do not update the CI, it will stay on nightly.
\ No newline at end of file
diff --git a/src/migrating-to-v1/v1-changes.md b/src/migrating-to-v1/v1-changes.md
new file mode 100644
index 000000000..805798317
--- /dev/null
+++ b/src/migrating-to-v1/v1-changes.md
@@ -0,0 +1,3 @@
+## Breaking and Non-Breaking Changes in V1
+
+With the V1 release, some breaking changes have been made which might require you to tweak your tests, and some patterns are now discouraged and might emit warnings. This guide will help you understand what these changes are and how to handle them properly.
\ No newline at end of file