From cc98e2fa22d371c80bc1a8396c8e7bf1be886670 Mon Sep 17 00:00:00 2001
From: Ariel Elperin <ariel@starkware.co>
Date: Fri, 24 Nov 2023 16:46:43 +0200
Subject: [PATCH] refactor simulateTransactions and estimateFee

---
 api/starknet_api_openrpc.json       | 62 +++++++++++++++++++++++------
 api/starknet_trace_api_openrpc.json |  5 +--
 2 files changed, 50 insertions(+), 17 deletions(-)

diff --git a/api/starknet_api_openrpc.json b/api/starknet_api_openrpc.json
index 91f92ac..445be5a 100644
--- a/api/starknet_api_openrpc.json
+++ b/api/starknet_api_openrpc.json
@@ -582,7 +582,7 @@
         {
             "name": "starknet_estimateFee",
             "summary": "estimate the fee for of StarkNet transactions",
-            "description": "estimates the resources required by transactions when applyed on a given state",
+            "description": "Estimates the resources required by a given sequence of transactions when applied on a given state. If one of the transaction reverts, a TRANSACTION_EXECUTION_ERROR is returned.",
             "params": [
                 {
                     "name": "request",
@@ -597,6 +597,17 @@
                     },
                     "required": true
                 },
+                {
+                    "name": "simulation_flags",
+                    "description": "describes what parts of the transaction should be executed",
+                    "required": false,
+                    "schema": {
+                        "type": "array",
+                        "items": {
+                            "$ref": "#/components/schemas/SIMULATION_FLAG_FOR_ESTIMATE_FEE"
+                        }
+                    }
+                },
                 {
                     "name": "block_id",
                     "description": "The hash of the requested block, or number (height) of the requested block, or a block tag, for the block referencing the state or call the transaction on.",
@@ -621,10 +632,7 @@
             },
             "errors": [
                 {
-                    "$ref": "#/components/errors/CONTRACT_NOT_FOUND"
-                },
-                {
-                    "$ref": "#/components/errors/CONTRACT_ERROR"
+                    "$ref": "#/components/errors/TRANSACTION_EXECUTION_ERROR"
                 },
                 {
                     "$ref": "#/components/errors/BLOCK_NOT_FOUND"
@@ -662,9 +670,6 @@
                 }
             },
             "errors": [
-                {
-                    "$ref": "#/components/errors/CONTRACT_NOT_FOUND"
-                },
                 {
                     "$ref": "#/components/errors/CONTRACT_ERROR"
                 },
@@ -3626,6 +3631,13 @@
                     "type"
                 ]
             },
+            "SIMULATION_FLAG_FOR_ESTIMATE_FEE": {
+                "type": "string",
+                "enum": [
+                    "SKIP_VALIDATE"
+                ],
+                "description": "Flags that indicate how to simulate a given transaction. By default, the sequencer behavior is replicated locally"
+            },
             "FEE_ESTIMATE": {
                 "title": "Fee estimation",
                 "type": "object",
@@ -3667,7 +3679,7 @@
                         "type": "string",
                         "enum": [
                             "WEI",
-                            "STRK"
+                            "FRI"
                         ]
                     }
                 },
@@ -3726,9 +3738,9 @@
             "RESOURCE_PRICE": {
                 "type": "object",
                 "properties": {
-                    "price_in_strk": {
-                        "title": "price in strk",
-                        "description": "the price of one unit of the given resource, denominated in strk",
+                    "price_in_fri": {
+                        "title": "price in fri",
+                        "description": "the price of one unit of the given resource, denominated in fri (10^-18 strk)",
                         "$ref": "#/components/schemas/FELT"
                     },
                     "price_in_wei": {
@@ -3739,7 +3751,7 @@
                 },
                 "required": [
                     "price_in_wei",
-                    "price_in_strk"
+                    "price_in_fri"
                 ]
             },
             "EXECUTION_RESOURCES": {
@@ -3889,6 +3901,30 @@
                     },
                     "required": "revert_error"
                 }
+            },
+            "TRANSACTION_EXECUTION_ERROR": {
+                "code": 40,
+                "message": "Transaction execution error",
+                "data": {
+                    "type": "object",
+                    "description": "More data about the execution failure",
+                    "properties": {
+                        "transaction_index": {
+                            "title": "Transaction index",
+                            "description": "The index of the first transaction failing in a sequence of given transactions",
+                            "type": "integer"
+                        },
+                        "revert_error": {
+                            "title": "revert error",
+                            "description": "a string encoding the execution trace up to the point of failure",
+                            "type": "string"
+                        }
+                    },
+                    "required": [
+                        "transaction_index",
+                        "revert_error"
+                    ]
+                }
             }
         }
     }
diff --git a/api/starknet_trace_api_openrpc.json b/api/starknet_trace_api_openrpc.json
index a1d50f1..fab3039 100644
--- a/api/starknet_trace_api_openrpc.json
+++ b/api/starknet_trace_api_openrpc.json
@@ -39,7 +39,7 @@
         },
         {
             "name": "starknet_simulateTransactions",
-            "summary": "simulate a given sequence of transactions on the requested state, and generate the execution traces. If one of the transactions is reverted, raises CONTRACT_ERROR.",
+            "summary": "Simulate a given sequence of transactions on the requested state, and generate the execution traces. Note that some of the transactions may revert, in which case no error is thrown, but revert details can be seen on the returned trace object.",
             "params": [
                 {
                     "name": "block_id",
@@ -99,9 +99,6 @@
                 {
                     "$ref": "#/components/errors/CONTRACT_NOT_FOUND"
                 },
-                {
-                    "$ref": "#/components/errors/CONTRACT_ERROR"
-                },
                 {
                     "$ref": "#/components/errors/BLOCK_NOT_FOUND"
                 }