Properly handle clear state program errors

algorand · Jan 4, 2024 · 44a4b75 · 44a4b75
1 parent d4a1b8b
commit 44a4b75
Show file tree

Hide file tree

Showing 11 changed files with 710 additions and 9 deletions.
diff --git a/FEATURES.md b/FEATURES.md
@@ -47,6 +47,10 @@ Execution errors will be reported by the debugger. Since any error stops the exe
 transaction group, the debugger will not allow you to advance after an error. You can however step
 backwards to inspect what happened prior to the error.
 
+> Note: There are a special class of errors which do not stop the execution of a transaction group.
+> These are errors or rejections that occur in a clear state program. The debugger will still show
+> these errors, and it will allow you to continue execution over them.
+
 ![An error in the debugger](images/error.png)
 
 ## Inspect program state

diff --git a/algosdk/client/v2/algod/models/types.d.ts b/algosdk/client/v2/algod/models/types.d.ts
@@ -2316,6 +2316,17 @@ export declare class SimulationTransactionExecTrace extends BaseModel {
      * Program trace that contains a trace of opcode effects in a clear state program.
      */
     clearStateProgramTrace?: SimulationOpcodeTraceUnit[];
+    /**
+     * If true, indicates that the clear state program failed and any persistent state
+     * changes it produced should be reverted once the program exits.
+     */
+    clearStateRollback?: boolean;
+    /**
+     * The error message explaining why the clear state program failed. This field will
+     * only be populated if clear-state-rollback is true and the failure was due to an
+     * execution error.
+     */
+    clearStateRollbackError?: string;
     /**
      * An array of SimulationTransactionExecTrace representing the execution trace of
      * any inner transactions executed.
@@ -2335,16 +2346,23 @@ export declare class SimulationTransactionExecTrace extends BaseModel {
      * @param approvalProgramTrace - Program trace that contains a trace of opcode effects in an approval program.
      * @param clearStateProgramHash - SHA512_256 hash digest of the clear state program executed in transaction.
      * @param clearStateProgramTrace - Program trace that contains a trace of opcode effects in a clear state program.
+     * @param clearStateRollback - If true, indicates that the clear state program failed and any persistent state
+     * changes it produced should be reverted once the program exits.
+     * @param clearStateRollbackError - The error message explaining why the clear state program failed. This field will
+     * only be populated if clear-state-rollback is true and the failure was due to an
+     * execution error.
      * @param innerTrace - An array of SimulationTransactionExecTrace representing the execution trace of
      * any inner transactions executed.
      * @param logicSigHash - SHA512_256 hash digest of the logic sig executed in transaction.
      * @param logicSigTrace - Program trace that contains a trace of opcode effects in a logic sig.
      */
-    constructor({ approvalProgramHash, approvalProgramTrace, clearStateProgramHash, clearStateProgramTrace, innerTrace, logicSigHash, logicSigTrace, }: {
+    constructor({ approvalProgramHash, approvalProgramTrace, clearStateProgramHash, clearStateProgramTrace, clearStateRollback, clearStateRollbackError, innerTrace, logicSigHash, logicSigTrace, }: {
         approvalProgramHash?: string | Uint8Array;
         approvalProgramTrace?: SimulationOpcodeTraceUnit[];
         clearStateProgramHash?: string | Uint8Array;
         clearStateProgramTrace?: SimulationOpcodeTraceUnit[];
+        clearStateRollback?: boolean;
+        clearStateRollbackError?: string;
         innerTrace?: SimulationTransactionExecTrace[];
         logicSigHash?: string | Uint8Array;
         logicSigTrace?: SimulationOpcodeTraceUnit[];

diff --git a/algosdk/client/v2/algod/models/types.js b/algosdk/client/v2/algod/models/types.js
@@ -2706,12 +2706,17 @@ class SimulationTransactionExecTrace extends basemodel_1.default {
      * @param approvalProgramTrace - Program trace that contains a trace of opcode effects in an approval program.
      * @param clearStateProgramHash - SHA512_256 hash digest of the clear state program executed in transaction.
      * @param clearStateProgramTrace - Program trace that contains a trace of opcode effects in a clear state program.
+     * @param clearStateRollback - If true, indicates that the clear state program failed and any persistent state
+     * changes it produced should be reverted once the program exits.
+     * @param clearStateRollbackError - The error message explaining why the clear state program failed. This field will
+     * only be populated if clear-state-rollback is true and the failure was due to an
+     * execution error.
      * @param innerTrace - An array of SimulationTransactionExecTrace representing the execution trace of
      * any inner transactions executed.
      * @param logicSigHash - SHA512_256 hash digest of the logic sig executed in transaction.
      * @param logicSigTrace - Program trace that contains a trace of opcode effects in a logic sig.
      */
-    constructor({ approvalProgramHash, approvalProgramTrace, clearStateProgramHash, clearStateProgramTrace, innerTrace, logicSigHash, logicSigTrace, }) {
+    constructor({ approvalProgramHash, approvalProgramTrace, clearStateProgramHash, clearStateProgramTrace, clearStateRollback, clearStateRollbackError, innerTrace, logicSigHash, logicSigTrace, }) {
         super();
         this.approvalProgramHash =
             typeof approvalProgramHash === 'string'
@@ -2723,6 +2728,8 @@ class SimulationTransactionExecTrace extends basemodel_1.default {
                 ? (0, binarydata_1.base64ToBytes)(clearStateProgramHash)
                 : clearStateProgramHash;
         this.clearStateProgramTrace = clearStateProgramTrace;
+        this.clearStateRollback = clearStateRollback;
+        this.clearStateRollbackError = clearStateRollbackError;
         this.innerTrace = innerTrace;
         this.logicSigHash =
             typeof logicSigHash === 'string'
@@ -2734,6 +2741,8 @@ class SimulationTransactionExecTrace extends basemodel_1.default {
             approvalProgramTrace: 'approval-program-trace',
             clearStateProgramHash: 'clear-state-program-hash',
             clearStateProgramTrace: 'clear-state-program-trace',
+            clearStateRollback: 'clear-state-rollback',
+            clearStateRollbackError: 'clear-state-rollback-error',
             innerTrace: 'inner-trace',
             logicSigHash: 'logic-sig-hash',
             logicSigTrace: 'logic-sig-trace',
@@ -2751,6 +2760,8 @@ class SimulationTransactionExecTrace extends basemodel_1.default {
             clearStateProgramTrace: typeof data['clear-state-program-trace'] !== 'undefined'
                 ? data['clear-state-program-trace'].map(SimulationOpcodeTraceUnit.from_obj_for_encoding)
                 : undefined,
+            clearStateRollback: data['clear-state-rollback'],
+            clearStateRollbackError: data['clear-state-rollback-error'],
             innerTrace: typeof data['inner-trace'] !== 'undefined'
                 ? data['inner-trace'].map(SimulationTransactionExecTrace.from_obj_for_encoding)
                 : undefined,

diff --git a/sampleWorkspace/.vscode/launch.json b/sampleWorkspace/.vscode/launch.json
@@ -142,6 +142,26 @@
       "simulateTraceFile": "${workspaceFolder}/errors/logicsig-after-error/simulate-response.json",
       "programSourcesDescriptionFile": "${workspaceFolder}/errors/logicsig-after-error/sources.json",
 
+      "stopOnEntry": true
+    },
+    {
+      "type": "avm",
+      "request": "launch",
+      "name": "Clear State Rejection",
+
+      "simulateTraceFile": "${workspaceFolder}/errors/clear-state/rejection-response.json",
+      "programSourcesDescriptionFile": "${workspaceFolder}/errors/clear-state/sources.json",
+
+      "stopOnEntry": true
+    },
+    {
+      "type": "avm",
+      "request": "launch",
+      "name": "Clear State Error",
+
+      "simulateTraceFile": "${workspaceFolder}/errors/clear-state/error-response.json",
+      "programSourcesDescriptionFile": "${workspaceFolder}/errors/clear-state/sources.json",
+
       "stopOnEntry": true
     }
   ]

diff --git a/sampleWorkspace/errors/clear-state/error-response.json b/sampleWorkspace/errors/clear-state/error-response.json
@@ -0,0 +1,180 @@
+{
+  "exec-trace-config": {
+    "enable": true,
+    "scratch-change": true,
+    "stack-change": true,
+    "state-change": true
+  },
+  "initial-states": {
+    "app-initial-states": [
+      {
+        "app-globals": {
+          "kvs": [
+            {
+              "key": "Y291bnRlcg==",
+              "value": {
+                "type": 2,
+                "uint": 4
+              }
+            }
+          ]
+        },
+        "id": 1001
+      }
+    ]
+  },
+  "last-round": 4,
+  "txn-groups": [
+    {
+      "app-budget-added": 700,
+      "app-budget-consumed": 14,
+      "txn-results": [
+        {
+          "app-budget-consumed": 14,
+          "exec-trace": {
+            "clear-state-program-hash": "ZY8dOBgLGyQoqiQqBH1PSo+dCcJIDpwqLzqLBvNJaNk=",
+            "clear-state-program-trace": [
+              {
+                "pc": 1
+              },
+              {
+                "pc": 4,
+                "stack-additions": [
+                  {
+                    "bytes": "Y291bnRlcg==",
+                    "type": 1
+                  }
+                ]
+              },
+              {
+                "pc": 13,
+                "stack-additions": [
+                  {
+                    "bytes": "Y291bnRlcg==",
+                    "type": 1
+                  },
+                  {
+                    "bytes": "Y291bnRlcg==",
+                    "type": 1
+                  }
+                ],
+                "stack-pop-count": 1
+              },
+              {
+                "pc": 14,
+                "stack-additions": [
+                  {
+                    "type": 2,
+                    "uint": 4
+                  }
+                ],
+                "stack-pop-count": 1
+              },
+              {
+                "pc": 15,
+                "stack-additions": [
+                  {
+                    "type": 2,
+                    "uint": 1
+                  }
+                ]
+              },
+              {
+                "pc": 16,
+                "stack-additions": [
+                  {
+                    "type": 2,
+                    "uint": 5
+                  }
+                ],
+                "stack-pop-count": 2
+              },
+              {
+                "pc": 17,
+                "stack-pop-count": 2,
+                "state-changes": [
+                  {
+                    "app-state-type": "g",
+                    "key": "Y291bnRlcg==",
+                    "new-value": {
+                      "type": 2,
+                      "uint": 5
+                    },
+                    "operation": "w"
+                  }
+                ]
+              },
+              {
+                "pc": 18,
+                "stack-additions": [
+                  {
+                    "type": 2,
+                    "uint": 1001
+                  }
+                ]
+              },
+              {
+                "pc": 20,
+                "stack-pop-count": 1
+              },
+              {
+                "pc": 23,
+                "stack-additions": [
+                  {
+                    "type": 2,
+                    "uint": 3
+                  }
+                ]
+              },
+              {
+                "pc": 25,
+                "stack-additions": [
+                  {
+                    "type": 2,
+                    "uint": 1
+                  }
+                ]
+              },
+              {
+                "pc": 26,
+                "stack-additions": [
+                  {
+                    "type": 2
+                  }
+                ],
+                "stack-pop-count": 2
+              },
+              {
+                "pc": 27,
+                "stack-pop-count": 1
+              },
+              {
+                "pc": 30
+              }
+            ],
+            "clear-state-rollback": true,
+            "clear-state-rollback-error": "invalid ApplicationArgs index 0"
+          },
+          "txn-result": {
+            "pool-error": "",
+            "txn": {
+              "sig": "Q0UCQSgS7KBWT+N/xXFELqajmZatiAp4NZgoOJRLoEKRGwUkr0/E7BMOybspT7BIVa0vCpjN0l8O/ePdcs9EAg==",
+              "txn": {
+                "apan": 3,
+                "apid": 1001,
+                "fee": 1000,
+                "fv": 4,
+                "gh": "dsgtQlDfh3EgBWQs+f6G+ZorH4WiY2Vmzu7sGgfcbng=",
+                "lv": 1004,
+                "note": "sV/32BiFDlA=",
+                "snd": "EI4F6GLWBIUTRCC4EJK7TXKY4AEW6DOZNUXYZXYEHBPXNFJU53REVFPI34",
+                "type": "appl"
+              }
+            }
+          }
+        }
+      ]
+    }
+  ],
+  "version": 2
+}