Algod: Simulate endpoint stack-change exposure

cmd/goal/clerk.go

@@ -74,6 +74,7 @@
 	simulateAllowMoreOpcodeBudget bool
 	simulateExtraOpcodeBudget     uint64
 	simulateEnableRequestTrace    bool
+	simulateStackChange           bool
 )
 
 func init() {
@@ -163,6 +164,7 @@
 	simulateCmd.Flags().BoolVar(&simulateAllowMoreOpcodeBudget, "allow-more-opcode-budget", false, "Apply max extra opcode budget for apps per transaction group (default 320000) during simulation")
 	simulateCmd.Flags().Uint64Var(&simulateExtraOpcodeBudget, "extra-opcode-budget", 0, "Apply extra opcode budget for apps per transaction group during simulation")
 	simulateCmd.Flags().BoolVar(&simulateEnableRequestTrace, "trace", false, "Enable simulation time execution trace of app calls")
+	simulateCmd.Flags().BoolVar(&simulateStackChange, "stack", false, "Report stack change during simulation time")
 }
 
 var clerkCmd = &cobra.Command{
@@ -1366,5 +1368,6 @@
 func traceCmdOptionToSimulateTraceConfigModel() simulation.ExecTraceConfig {
 	return simulation.ExecTraceConfig{
 		Enable: simulateEnableRequestTrace,
+		Stack:  simulateStackChange,
 	}
 }

daemon/algod/api/algod.oas2.json

@@ -3108,6 +3108,29 @@
         }
       }
     },
+    "StackValue": {
+      "description": "Represents a TEAL value over the stack.",
+      "type": "object",
+      "required": [
+        "type"
+      ],
+      "properties": {
+        "type": {
+          "description": "value type. Value `1` refers to **bytes**, value `2` refers to **uint**",
+          "type": "integer"
+        },
+        "bytes": {
+          "description": "bytes value.",
+          "type": "string",
+          "format": "byte"
+        },
+        "uint": {
+          "description": "uint value.",
+          "type": "integer",
+          "x-algorand-format": "uint64"
+        }
+      }
+    },
     "StateDelta": {
       "description": "Application state delta.",
       "type": "array",
@@ -3491,6 +3514,10 @@
         "enable": {
           "description": "A boolean option for opting in execution trace features simulation endpoint.",
           "type": "boolean"
+        },
+        "stack-change": {
+          "description": "A boolean option enabling returning stack changes together with execution trace during simulation.",
+          "type": "boolean"
         }
       }
     },
@@ -3870,6 +3897,20 @@
           "items": {
             "type": "integer"
           }
+        },
+        "deletions": {
+          "description": "The values deleted by this opcode from the stack.",
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/StackValue"
+          }
+        },
+        "additions": {
+          "description": "The values added by this opcode to the stack.",
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/StackValue"
+          }
         }
       }
     },

daemon/algod/api/algod.oas3.yml

@@ -1966,6 +1966,10 @@
           "enable": {
             "description": "A boolean option for opting in execution trace features simulation endpoint.",
             "type": "boolean"
+          },
+          "stack-change": {
+            "description": "A boolean option enabling returning stack changes together with execution trace during simulation.",
+            "type": "boolean"
           }
         },
         "type": "object"
@@ -2053,6 +2057,20 @@
       "SimulationOpcodeTraceUnit": {
         "description": "The set of trace information and effect from evaluating a single opcode.",
         "properties": {
+          "additions": {
+            "description": "The values added by this opcode to the stack.",
+            "items": {
+              "$ref": "#/components/schemas/StackValue"
+            },
+            "type": "array"
+          },
+          "deletions": {
+            "description": "The values deleted by this opcode from the stack.",
+            "items": {
+              "$ref": "#/components/schemas/StackValue"
+            },
+            "type": "array"
+          },
           "pc": {
             "description": "The program counter of the current opcode being evaluated.",
             "type": "integer"
@@ -2104,6 +2122,30 @@
         },
         "type": "object"
       },
+      "StackValue": {
+        "description": "Represents a TEAL value over the stack.",
+        "properties": {
+          "bytes": {
+            "description": "bytes value.",
+            "format": "byte",
+            "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$",
+            "type": "string"
+          },
+          "type": {
+            "description": "value type. Value `1` refers to **bytes**, value `2` refers to **uint**",
+            "type": "integer"
+          },
+          "uint": {
+            "description": "uint value.",
+            "type": "integer",
+            "x-algorand-format": "uint64"
+          }
+        },
+        "required": [
+          "type"
+        ],
+        "type": "object"
+      },
       "StateDelta": {
         "description": "Application state delta.",
         "items": {