[debug] Add a debug guide

Author: gregnazario

apps/nextra/pages/en/build/smart-contracts/_meta.tsx

@@ -19,6 +19,9 @@ export default {
   deployment: {
     title: "Deployment",
   },
+  debugging: {
+    title: "Debugging",
+  },
   "---aptos-standards---": {
     type: "separator",
     title: "Aptos Standards",

apps/nextra/pages/en/build/smart-contracts/debugging.mdx

@@ -0,0 +1,105 @@
+---
+title: "Debugging Move"
+---
+
+# Debugging Move
+
+Move was designed to be simple and safe, but like with all programming languages,
+bugs can still occur. This guide will help you debug your Move code and figure out
+what went wrong.
+
+Please feel free to contribute with additional tooling and information that can
+help others in the community.
+
+## Debugging with the Aptos CLI
+
+### Simulation on transaction submission
+
+You can use the Aptos CLI to simulate entry functions prior to executing them.
+
+Normally, a transaction will fail in simulation if it won't work on-chain. For example:
+
+```bash name="Terminal"
+aptos move run --function-id 0x1::aptos_account::transfer --args address:0x1 u64:1000000000000000000
+{
+  "Error": "Simulation failed with status: Move abort in 0x1::coin: EINSUFFICIENT_BALANCE(0x10006): Not enough coins to complete transaction"
+}
+```
+
+The same applies to Move scripts as well. For example:
+
+```bash name="Terminal"
+ aptos move run-script --script-path <script_path> ...
+```
+
+### Local Simulation
+
+Additionally, for some situations, local simulation, may give additional information and
+[print out any debug statements you have in your code](https://aptos.dev/en/build/cli/working-with-move-contracts#printing-debugging-information).
+
+```bash name="Terminal"
+aptos move run --function-id 0x1::aptos_account::transferred --args address:0x1 u64:1000000000000000000 --local
+
+Simulating transaction locally...
+{
+  "Result": {
+    "transaction_hash": "0x4115316915d409ba4106632c82d4b09220035ffdbd0b86bbe29a586d03d06318",
+    "gas_used": 3,
+    "gas_unit_price": 100,
+    "sender": "78077fe8db589e1a3407170cf8af3bd60a8c95737918c15dd6f49dcbecc7900a",
+    "success": false,
+    "version": 56634003,
+    "vm_status": "status FUNCTION_RESOLUTION_FAILURE of type Verification with message Function 0x1::aptos_account::transferred does not exist"
+  }
+}
+```
+
+### Gas Profiling and Tracing
+
+Adding the gas profile will additionally add the ability to trace how much gas is
+used in computation:
+
+```bash name="Terminal"
+aptos move run --function-id 0x1::aptos_account::transferred --args address:0x1 u64:1000000000000000000 --profile-gas
+
+Simulating transaction locally using the gas profiler...
+Gas report saved to gas-profiling/txn-a90ca655-0x1-aptos_account-transferred.
+{
+  "Result": {
+    "transaction_hash": "0xa90ca6550dcdd7f514f4cdcdee7dc1fbee17082fcf68f3db3e5755a93b89bcfc",
+    "gas_used": 3,
+    "gas_unit_price": 100,
+    "sender": "78077fe8db589e1a3407170cf8af3bd60a8c95737918c15dd6f49dcbecc7900a",
+    "success": false,
+    "version": 56651618,
+    "vm_status": "status FUNCTION_RESOLUTION_FAILURE of type Verification with message Function 0x1::aptos_account::transferred does not exist"
+  }
+}
+```
+
+And this will generate a gas report viewable in HTML format:
+
+```bash name="Terminal"
+open  gas-profiling/txn-a90ca655-0x1-aptos_account-transferred/index.html
+```
+
+## Evaluating performance
+
+```bash name="Terminal"
+aptos move run --function-id 0x1::aptos_account::transfer --args address:0x1 u64:1 --benchmark
+
+Benchmarking transaction locally...
+Running time (cold code cache): 22.144458ms
+Running time (warm code cache): 669.5µs
+{
+  "Result": {
+    "transaction_hash": "0x7cdf37ff4d798b3ac3f1e860a40428853e381598a511b9291f2a49e5ff6262a0",
+    "gas_used": 11,
+    "gas_unit_price": 100,
+    "sender": "78077fe8db589e1a3407170cf8af3bd60a8c95737918c15dd6f49dcbecc7900a",
+    "success": true,
+    "version": 56679764,
+    "vm_status": "status EXECUTED of type Execution"
+  }
+}
+```