Merge branch 'master' into montyly-patch-1

Author: montyly

SUMMARY.md

@@ -88,6 +88,7 @@
       - [How to seed Echidna with unit tests](./program-analysis/echidna/advanced/end-to-end-testing.md)
       - [Understanding and using `allContracts`](./program-analysis/echidna/advanced/using-all-contracts.md)
       - [How to fuzz contracts with external libraries](./program-analysis/echidna/advanced/working-with-libraries.md)
+      - [How to do on-chain fuzzing with state forking](./program-analysis/echidna/advanced/state-network-forking.md)
       - [Interacting with off-chain data via FFI cheatcode](./program-analysis/echidna/advanced/interacting-with-offchain-data-via-ffi.md)
     - [Fuzzing tips](./program-analysis/echidna/fuzzing_tips.md)
     - [Frequently Asked Questions](./program-analysis/echidna/frequently_asked_questions.md)

development-guidelines/incident_response.md

@@ -1,49 +1,59 @@
-# Incident Response Guidelines
+# Incident Response Recommendations
 
-How you respond during an incident is a direct reflection of your efforts to prepare for such an event. Adherance to our guidelines can help you shift from a reactive approach to a **proactive** approach by planning with the assumption that incidents are inevitable. To fully leverage the following guidelines, consider them throughout the application development process.
+How you respond during an incident is a direct reflection of your efforts to prepare for such an event. Each team or project's needs will vary so we provide the guidelines below as a starting point. Adherance to our guidelines can help you shift from a reactive approach to a **proactive** approach by planning with the assumption that incidents are inevitable. To fully leverage the following guidelines, consider them throughout the application development process.
 
-## Application design
+## Application Design
 
-- **Identify the components that should/should not be**
+- **Identify which components should or should not be:**
   - **Pausable**. While pausing a component can be beneficial during an incident, you must assess its potential impact on other contracts.
   - **Migratable or upgradeable**. Discovering a bug might necessitate a [migration strategy](https://blog.trailofbits.com/2018/10/29/how-contract-migration-works/) or contract upgrade to fix the issue; note, however, that upgradeability has its own [sets of risks](https://blog.trailofbits.com/2020/12/16/breaking-aave-upgradeability/). Making all contracts upgradeable might not be the best approach.
-  - **Decentralized**. Using decentralized components can sometimes restrict rescue measures.
-- **Evaluate what events are needed**. A missed event in a critical location might result in unnoticed incidents.
+  - **Decentralized**. Using decentralized components can sometimes limit what rescue measures are possible and may require a higher amount of coordination.
+- **Begin to identify important system invariants**. This helps to determine what you will need to monitor and what events may be necessary to do so effectively.
+- **Evaluate what additional events are needed**. A missed event in a critical location might result in unnoticed incidents.
 - **Evaluate what components must be on-chain and off-chain**. On-chain components are generally more at risk, but off-chain components push the risks to the off-chain owner.
-- **Use an access control that allows fine-grained access**. Avoid setting all access controls to be available to an EOA. Opt for multisig wallets/MPC, and segregate access (e.g., the key responsible for setting fees shouldn't have access to the upgradeability feature).
+- **Use fine-grained access controls**. Avoid setting all access controls to be available to an EOA. Opt for multisig wallets/MPC, and avoid delegating several roles to one address (e.g., the key responsible for setting fees shouldn't have access to the upgradeability feature).
 
 ## Documentation
 
-- **Document how to interpret abnormal events emission**. Only emitting events isn't sufficient; proper documentation is crucial, and users should be empowered to decode them.
-- **Document how to access wallets**. Clearly outline how to access wallets. Both the location and access procedures for every wallet should be clear and straightforward.
-- **Document the deployment and upgrade process**. Deployment and upgrade processes are risky and must be thoroughly documented. This should include how to test the deployment/upgrade (ex: using fork testing) and how to validate it (ex: using a post-deployment script).
-- **Document how to contact the users and external dependencies**. Define guidelines regarding which stakeholders to contact, including the timing and mode of communication in case of incidents.
+- **Assemble a runbook of common actions you may need to perform**. It's not possible or practical to exhaustively detail how you'll respond to every type of incident. But you _can_ start to document procedures for some of the more important ones as well as actions that might be common across multiple scenarios (e.g., pausing, rotating owner keys, upgrading an implementation). This can also include scripts or snippets of code to facilitate performing these actions in a reproducible manner.
+- **Document how to interpret events emission**. Only emitting events isn't sufficient; proper documentation is crucial, and users should be empowered to identify and decode them.
+- **Document how to access wallets**. Clearly outline how to access wallets with special roles in the system. This should include both the location as well as access procedures for each wallet.
+- **Document the deployment and upgrade process**. Deployment and upgrade processes are risky and must be thoroughly documented. This should include how to test the deployment/upgrade (e.g., using fork testing) and how to validate it (e.g., using a post-deployment script).
+- **Document how to contact users and external dependencies**. Define guidelines regarding which stakeholders to contact, including the timing and mode of communication in case of incidents. The right communication at the right time is key to maintaining trust.
 
 ## Process
 
 - **Conduct periodic training and incident response exercises**. Regularly organize training sessions and incident response exercises. Such measures ensure that employees remain updated and can help highlight any flaws in the current incident response protocol.
+- **Remember to consider off-chain components when planning**. While much of this document is concerned with on-chain code, compromised frontends or social media accounts are also common sources of incidents.
 - **Identify incident owners, with at least**:
   - **A technical lead**. Responsible for gathering and centralizing technical data.
   - **A communication lead**. Tasked with internal and external communication.
   - **A legal lead**. Either provides legal advice or ensures the right legal entities are contacted. It might also be worth considering liaison with appropriate law enforcement agencies.
-- **Use automated monitoring tools**. Whether you opt for an in-house solution or third-party products, automation is key. While considering automated responses like pausing the system in the event of irregular activities, exercise caution. Without careful configuration, automatic responses might inadvertently facilitate denial-of-service (DOS) exploits.
+- **Use monitoring tools**. You may opt for a third-party product, an in-house solution, or a combination of both. Third-party montoring will identify more generally suspicious transactions but may not be as in tune with system-specific metrics like health factors, collateralization ratios, or if an AMM invariant starts to drift. In-house monitoring, on the other hand, requires more engineering effort to setup and maintain, but can be tailored specifically to your needs.
+- **Carefully consider automating certain actions based on monitoring alerts**. You may wish to automatically pause or move the system into a safer state if certain actvities are detected given how quickly some exploits are carried out. However, also keep in mind the impact and likelihood of a false positive triggering such a mechanism and how disruptive that could be.
 
 ## Threat Intelligence
 
-- **Identify similar protocols, and stay informed of related compromises**. Being aware of vulnerabilities in similar systems can help preemptively address potential threats in your own.
-- **Identify dependencies, and monitor their behaviors to be alerted in case of compromise.** Follow twitter, discord, newsletter, etc.
-- **Maintain open communication lines with your dependencies owners**. This will help you to stay informed if one of your dependency is compromised.
-- **Subscribe to https://newsletter.blockthreat.io/**. BlockThreat will help you stay informed about recent incidents.
+- **Identify similar protocols, and stay informed of any issues affecting them**. This could include forks, implementations on other chains, or protocols in the same general class (e.g., other lending protocols). Being aware of vulnerabilities in similar systems can help preemptively address potential threats in your own.
+- **Identify your dependencies, and follow their communication channels to be alerted in case of an issue.** Follow their Twitter, Discord, Telegram, newsletter, etc. This includes both on-chain as well as off-chain (e.g., libraries, toolchain) dependencies.
+- **Maintain open communication lines with your dependencies' owners**. This will help you to stay informed if one of your dependencies is compromised.
+- **Subscribe to the [BlockThreat](https://newsletter.blockthreat.io/) newsletter**. BlockThreat will keep you informed about recent incidents and developments in blockchain security. The nature of blockchains means we have a culture of learning in the open so take advantage of this and learn from your peers.
 
 Additionally, consider conducting a threat modeling exercise. This exercise will identify risks that an application faces at both the structural and operational level. If you're interested in undertaking such an exercise and would like to work with us, [contact us](https://www.trailofbits.com/contact/).
 
-## Incident Response Plan Resources
+## Resources
 
+- [An Incident Response Plan for Startups](https://medium.com/starting-up-security/an-incident-response-plan-for-startups-26549596b914)
+  - A minimum viable incident response plan, a great starting point for a smaller team. Especially in combination with the Yearn example below, which is tailored a bit more for web3 teams.
+- [The practical guide to incident management](https://incident.io/guide)
+  - An approachable guide for incident response. Chapter 4 includes examples for how to approach practicing your process.
+- [PagerDuty Incident Response](https://response.pagerduty.com/)
+  - A _very_ detailed handbook of how PagerDuty handles incident response themselves. Some useful ideas and resources, but more practical for larger organizations.
 - [How to Hack the Yield Protocol](https://docs.yieldprotocol.com/#/operations/how_to_hack)
-- [Emergency Steps – Yearn](https://github.com/yearn/yearn-devdocs/blob/master/docs/developers/v2/EMERGENCY.md)
-- [Monitoring & Incident Response - Heidi Wilder (DSS 2023)](https://www.youtube.com/watch?v=TDlkkg8N0wc)
+- [Emergency Procedures for Yearn Finance](https://github.com/yearn/yearn-devdocs/blob/master/docs/developers/v2/EMERGENCY.md)
+- [Rekt pilled: What to do when your dApp gets pwned and how to stay kalm - Heidi Wilder (DSS 2023)](https://www.youtube.com/watch?v=TDlkkg8N0wc)
 - [Crisis Handbook - Smart Contract Hack (SEAL)](https://docs.google.com/document/d/1DaAiuGFkMEMMiIuvqhePL5aDFGHJ9Ya6D04rdaldqC0/edit)
 
-### Examples of incidents retrospective
+### Community Incident Retrospectives
 
 - [Yield Protocol](https://medium.com/yield-protocol/post-mortem-of-incident-on-august-5th-2022-7bb70dbb9ada)

learn_evm/evm_opcodes.md

@@ -78,7 +78,8 @@ The gas information is a work in progress. If an asterisk is in the Gas column,
 | [`0x59`](#msize)          | MSIZE          | Get the size of active memory in bytes                                                                                                                       | -                                                                                                         | 2           |
 | [`0x5a`](#gas)            | GAS            | Get the amount of available gas, including the corresponding reduction for the cost of this instruction                                                      | -                                                                                                         | 2           |
 | [`0x5b`](#jumpdest)       | JUMPDEST       | Mark a valid destination for jumps                                                                                                                           | -                                                                                                         | 1           |
-| `0x5c` - `0x5f`           | Unused         | -                                                                                                                                                            |
+| `0x5c` - `0x5e`           | Unused         | -                                                                                                                                                            |
+| [`0x5f`](#push0)          | PUSH0          | Place the constant value 0 on stack                                                                                                                          | [EIP-3855](https://eips.ethereum.org/EIPS/eip-3855)                                                       | 2           |
 | [`0x60`](#push1)          | PUSH1          | Place 1 byte item on stack                                                                                                                                   | -                                                                                                         | 3           |
 | [`0x61`](#push2)          | PUSH2          | Place 2-byte item on stack                                                                                                                                   | -                                                                                                         | 3           |
 | [`0x62`](#push3)          | PUSH3          | Place 3-byte item on stack                                                                                                                                   | -                                                                                                         | 3           |
@@ -816,6 +817,16 @@ noop, marks a valid jump destination
 
 ---
 
+### PUSH0
+
+**0x5f**
+
+The constant value 0 is pushed onto the stack.
+
+() => (0)
+
+---
+
 ### PUSH1
 
 **0x60**

program-analysis/echidna/advanced/smart-contract-fuzzing-at-scale.md

@@ -74,7 +74,7 @@ Once it runs, check the coverage file located in `corpus-exploration/covered.*.t
 
 ## 3. Initiate a continuous fuzzing campaign
 
-When satisfied with the first iteration of the initialization, we can start a "continuous campaign" for exploration and testing using [echidna-parade](https://github.com/agroce/echidna-parade). Before starting, double-check your config file. For instance, if you added properties, do not forget to remove `benchmarkMode`.
+When satisfied with the first iteration of the initialization, we can start a "continuous campaign" for exploration and testing using [echidna-parade](https://github.com/crytic/echidna-parade). Before starting, double-check your config file. For instance, if you added properties, do not forget to remove `benchmarkMode`.
 
 `echidna-parade` is a tool used to launch multiple Echidna instances simultaneously while keeping track of each corpus. Each instance will be configured to run for a specific duration, with different parameters, to maximize the chance of reaching new code.
 

program-analysis/echidna/basic/working-with-eth.md

@@ -116,4 +116,4 @@ echidna_C_has_some_value: failed!💥
 Echidna has two options for using ether during a fuzzing campaign.
 
 - `maxValue` to set the max amount of ether per transaction
-- `contractBalance` to set the initial amount of ether that the testing contract receives in the constructor.
+- `balanceContract` to set the initial amount of ether that the testing contract receives in the constructor.

program-analysis/echidna/exercises/Exercise-1.md

@@ -51,8 +51,11 @@ contract Token is Ownable, Pausable {
     mapping(address => uint256) public balances;
 
     function transfer(address to, uint256 value) public whenNotPaused {
-        balances[msg.sender] -= value;
-        balances[to] += value;
+        // unchecked to save gas
+        unchecked {
+            balances[msg.sender] -= value;
+            balances[to] += value;
+        }
     }
 }
 ```
@@ -79,8 +82,8 @@ import "./token.sol";
 contract TestToken is Token {
     address echidna = tx.origin;
 
-    constructor() public {
-        balances[echidna] = 10000;
+    constructor() {
+        balances[echidna] = 10_000;
     }
 
     function echidna_test_balance() public view returns (bool) {

program-analysis/echidna/exercises/Exercise-2.md

@@ -84,7 +84,7 @@ import "./token.sol";
 ///      echidna program-analysis/echidna/exercises/exercise2/template.sol
 ///      ```
 contract TestToken is Token {
-    constructor() public {
+    constructor() {
         pause(); // pause the contract
         owner = address(0); // lose ownership
     }

program-analysis/echidna/exercises/Exercise-3.md

@@ -19,7 +19,7 @@ We will test the following contract _[token.sol](https://github.com/crytic/build
 ```solidity
 pragma solidity ^0.8.0;
 
-/// @notice The issues from exercises 1 and 2 are fixed.
+/// @notice The issues from exercise 1 and 2 are fixed.
 
 contract Ownable {
     address public owner = msg.sender;
@@ -74,7 +74,7 @@ contract MintableToken is Token {
     int256 public totalMinted;
     int256 public totalMintable;
 
-    constructor(int256 totalMintable_) public {
+    constructor(int256 totalMintable_) {
         totalMintable = totalMintable_;
     }
 
@@ -111,7 +111,7 @@ contract TestToken is MintableToken {
     address echidna = msg.sender;
 
     // TODO: update the constructor
-    constructor(int256 totalMintable) public MintableToken(totalMintable) {}
+    constructor(int256 totalMintable) MintableToken(totalMintable) {}
 
     function echidna_test_balance() public view returns (bool) {
         // TODO: add the property

program-analysis/echidna/exercises/Exercise-4.md

@@ -27,7 +27,7 @@ contract Ownable {
     }
 
     modifier onlyOwner() {
-        require(msg.sender == owner, "Ownable: Caller is not the owner");
+        require(msg.sender == owner, "Ownable: Caller is not the owner.");
         _;
     }
 }
@@ -48,17 +48,20 @@ contract Pausable is Ownable {
     }
 
     modifier whenNotPaused() {
-        require(!_paused, "Pausable: Contract is paused");
+        require(!_paused, "Pausable: Contract is paused.");
         _;
     }
 }
 
 contract Token is Ownable, Pausable {
     mapping(address => uint256) public balances;
 
-    function transfer(address to, uint256 value) public whenNotPaused {
-        balances[msg.sender] -= value;
-        balances[to] += value;
+    function transfer(address to, uint256 value) public virtual whenNotPaused {
+        // unchecked to save gas
+        unchecked {
+            balances[msg.sender] -= value;
+            balances[to] += value;
+        }
     }
 }
 ```
@@ -88,6 +91,10 @@ import "./token.sol";
 ///      solc-select use 0.8.0
 ///      echidna program-analysis/echidna/exercises/exercise4/template.sol --contract TestToken --test-mode assertion
 ///      ```
+///      or by providing a config
+///      ```
+///      echidna program-analysis/echidna/exercises/exercise4/template.sol --contract TestToken --config program-analysis/echidna/exercises/exercise4/config.yaml
+///      ```
 contract TestToken is Token {
     function transfer(address to, uint256 value) public {
         // TODO: include `assert(condition)` statements that