Merge pull request #3201 from ethereum/pin1

update forking and saving VM state and misc on run.md

docs/running_js_scripts.md

@@ -62,7 +62,7 @@ The script can contains Mocha tests to be run.
 
 In order to connect a contract with a script, add the **NatSpec** tag `@custom:dev-run-script` to the contract followed by the absolute file path, like:
 
-```code
+```
   /**
    * @title ContractName
    * @dev ContractDescription

docs/tutorial_debug.md

@@ -63,9 +63,7 @@ Click the `Deploy` button
 
 You'll see the deployed instance (AKA the udapp).
 
-![](images/a-debug2-udapp1a.png)
-
-Then open it up (by clicking the caret).
+Open it up (by clicking the caret).
 
 ![](images/a-debug3-udapp2.png)
 

docs/udapp.md

@@ -1,68 +1,68 @@
 Deploy & Run (part 2)
 =====================
 
-## Deployed contracts
+## Interacting with deployed contracts
 
-This section in the Run tab contains a list of deployed contracts to interact with through autogenerated UI of the deployed contract (also called udapp).
+After a contract is deployed or after it is accessed with AtAddress, the deployed instance will appear in the **Deploy/Unpinned Contracts** section at the bottom of the Deploy & Run panel.
 
-The deployed contract appears but is in its collapsed form.
+![](images/a-deploy-run-deployed-instances.png)
 
-![](images/a-debug2-udapp1a.png)
+The deployed contract's address is visible as are a few other icons - one of which is the **pin** icon.  
 
-Click the sideways caret to open it up.
+## Pinned contracts
+When a contract is pinned, it will jump up to the **Pinned Contracts** section and Remix will save the contract's address and the ABI (in the .deploys folder of the current Workspace).  When Remix is refreshed, the pinned contracts will be loaded into the Pinned Contracts section.  
 
-![](images/a-udapp1.png)
+#### Pinned contracts are chain & Workspace specific
+Because a pinned contract's address and ABI are stored in a File Explorer Workspace, the same Workspace must be active to see its pinned contracts.  Similarly, only the pinned contracts of the currently selected chain will show.
 
-You will see the functions in the contract.  The functions buttons can have different color buttons.
+## Functions 
+To see a contract's functions, click the caret on the left side of the panel.
 
--   Functions that are `constant` or `pure` functions in Solidity have a blue buttons. Clicking one of this type does not create a new transaction. So clicking will not cause state changes - it will only return a value stored in the contract - so it won't cost you anything in gas fees.
+![](images/a-deploy-run-caret.png)
 
--   Functions that change the state of the contract AND that do not accept Ether are called `non-payable` functions and have an orange button. Clicking on them will create a transaction and thus cost gas.
+The functions' buttons can have different colors.
 
--   Functions that have red buttons are `payable` functions in Solidity. Clicking one of these will create a new transaction and this transaction can accept a **value**.  The **value** is put in in the Value field which is under the Gas Limit field.
+-   Blue buttons are for `view` or `pure` functions. Clicking a blue button does not create a new transaction - so there will be **no gas fees**.
+
+-   Orange buttons are for `non-payable` functions.  Non-payable functions change the state of the contract BUT **do not accept value** (typically ETH) being sent with the transaction. Clicking an orange button will create a transaction and will cost gas.
+
+-   Red buttons are for `payable` functions. Clicking a red button will create a new transaction and this transaction can accept a **value** (typically ETH).  The amount of value is set in in the **Value** field which is under the Gas Limit field.
 
 ![](images/a-jvm-calling-instance.png)
 
 
 See more information about [Solidity
-modifiers](https://solidity.readthedocs.io/en/develop/miscellaneous.html?highlight=pure#modifiers) in the Solidity docs.
-.
-
-If a function requires input parameters, well.. you gotta put them in.
+modifiers](https://docs.soliditylang.org/en/latest/cheatsheet.html#modifiers) - in the Solidity docs.
 
 ## Inputting parameters
+A function has two views - the collapsed and the expanded view, which is visible after clicking the caret on the right side of the panel.  
+
++ The input box shows the expected type of each parameter.
++ Numbers and addresses do not need to be wrapped in double quotes.  
++ Strings do not need to be wrapped.
 
 ![](images/a-udapp-inputs.png)
 
 ### Inputting parameters in the collapsed view
 
-(Inputting all the parameters in a single input box)
-+ The input box tells you what type each parameter needs to be.
-+ Numbers and addresses do not need to be wrapped in double quotes.  
-+ Strings do not need to be wrapped.
+In the collapsed view:
+
 + Parameters are separated by commas.
 
 In the example above the "delegate" function has 3 parameters.
 
 ### Inputting parameters in the expanded view
-Clicking the 'down' caret brings you to the *Multi-param Manager* - where you can input the parameters one at a time. **Much less confusing!**
+Clicking the 'down' caret brings you to the expanded view - where parameters are input one at a time. 
 
 ![](images/a-udapp-multi-param-man.png)
 
-In the expanded view, strings do not need to be wrapped.  
-
-Clicking the clipboard icon will encode the inputs and will copy them.  Only a valid set of inputs can be encoded.  
-
-So if you made a mistake and put a uint8 where an address should have been, clicking the clipboard here will give you an error.
-
 ## Low level interactions
 
 Low level interactions are used to send funds or calldata or funds & calldata to a contract through the **receive()** or **fallback()** function.  Typically, you should only need to implement the fallback function if you are following an upgrade or proxy pattern.
 
 The low level interactions section is below the functions in each deployed contract.
 
-![](images/a-udapp1.png)
-
+![](images/a-deploy-run-open-instance.png)
 
 Please note the following:
 
@@ -78,12 +78,12 @@ Please note the following:
 
 Please see the [solidity docs](https://solidity.readthedocs.io/en/latest/contracts.html#receive-ether-function) for more specifics about using the **fallback** and **receive** functions. 
 
-### Passing in a tuple or a struct to a function
-To pass a tuple in, you need to put in an array [].
+## Inputting a tuple or struct to a function
+To pass a tuple, you need to put in an array [].
+
+Similarly, to pass in a struct as a parameter of a function, it needs to be put in as an array [].  
 
-Similarly, to pass in a struct as a parameter of a function, it needs to be put in as an array [].  Also note that the line
-`pragma experimental ABIEncoderV2;`
-needs to put in at the top of the solidity file.
+**NOTE:** the file's pragma must be set to: `pragma experimental ABIEncoderV2;`
 
 ### Example of passing nested struct to a function
 Consider a nested struct defined like this: