Deprecate tracing API

CHANGELOG.md

@@ -32,6 +32,9 @@
 - Deprecated: [[#358](https://github.com/ethereum/evmc/pull/358)]
   The usage of `evmc/helpers.hpp` has been deprecated. Use `evmc/evmc.hpp`
   which provides the same features.
+- Deprecated: [[#376](https://github.com/ethereum/evmc/pull/376)]
+  The tracing API has been deprecated as there have been some design flaws discovered. 
+  New API is expected to be introduced in future.
 - Fixed:
   [[#261](https://github.com/ethereum/evmc/issues/261),
   [#263](https://github.com/ethereum/evmc/pull/263)]

examples/example_vm/example_vm.c

@@ -22,10 +22,8 @@
 /// The example VM instance struct extending the evmc_instance.
 struct example_vm
 {
-    struct evmc_instance instance;               ///< The base struct.
-    int verbose;                                 ///< The verbosity level.
-    evmc_trace_callback trace_callback;          ///< The trace callback.
-    struct evmc_tracer_context* tracer_context;  ///< The tracer context.
+    struct evmc_instance instance;  ///< The base struct.
+    int verbose;                    ///< The verbosity level.
 };
 
 /// The implementation of the evmc_instance::destroy() method.
@@ -169,16 +167,6 @@ static struct evmc_result execute(struct evmc_instance* instance,
     return ret;
 }
 
-/// The implementation of the optional evmc_instance::set_tracer() method.
-static void set_tracer(struct evmc_instance* instance,
-                       evmc_trace_callback callback,
-                       struct evmc_tracer_context* context)
-{
-    struct example_vm* vm = (struct example_vm*)instance;
-    vm->trace_callback = callback;
-    vm->tracer_context = context;
-}
-
 
 /// @cond internal
 #if !defined(PROJECT_VERSION)
@@ -197,7 +185,6 @@ struct evmc_instance* evmc_create_example_vm()
         .execute = execute,
         .get_capabilities = get_capabilities,
         .set_option = set_option,
-        .set_tracer = set_tracer,
     };
     struct example_vm* vm = calloc(1, sizeof(struct example_vm));
     struct evmc_instance* interface = &vm->instance;

include/evmc/evmc.h

@@ -859,7 +859,11 @@ typedef uint32_t evmc_capabilities_flagset;
  */
 typedef evmc_capabilities_flagset (*evmc_get_capabilities_fn)(struct evmc_instance* instance);
 
-/** The opaque type representing a Client-side tracer object. */
+/**
+ * The opaque type representing a Client-side tracer object.
+ *
+ * @deprecated Deprecated since EVMC 6.3, see evmc_instance::set_tracer().
+ */
 struct evmc_tracer_context;
 
 /**
@@ -871,6 +875,8 @@ struct evmc_tracer_context;
  * This piece of information can be acquired by inspecting messages being sent to the EVM in
  * ::evmc_execute_fn and the results of the messages execution.
  *
+ * @deprecated Deprecated since EVMC 6.3, see evmc_instance::set_tracer().
+ *
  * @param context                The pointer to the Client-side tracing context. This allows to
  *                               implement the tracer in OOP manner.
  * @param code_offset            The current instruction position in the code.
@@ -918,6 +924,8 @@ typedef void (*evmc_trace_callback)(struct evmc_tracer_context* context,
  *
  * This will overwrite the previous settings (the callback and the context).
  *
+ * @deprecated Deprecated since EVMC 6.3, see evmc_instance::set_tracer().
+ *
  * @param instance    The EVM instance.
  * @param callback    The tracer callback function. This argument MAY be NULL to disable previously
  *                    set tracer.
@@ -991,6 +999,10 @@ struct evmc_instance
      * Optional pointer to function setting the EVM instruction tracer.
      *
      * If the EVM does not support this feature the pointer can be NULL.
+     *
+     * @deprecated
+     * Since EVMC 6.3, the tracing API has been deprecated as there have been some
+     * design flaws discovered. New API is expected to be introduced in future.
      */
     evmc_set_tracer_fn set_tracer;
 

include/evmc/helpers.h

@@ -83,6 +83,7 @@ static inline enum evmc_set_option_result evmc_set_option(struct evmc_instance*
  *
  * @see evmc_set_tracer_fn
  */
+EVMC_DEPRECATED
 static inline void evmc_set_tracer(struct evmc_instance* instance,
                                    evmc_trace_callback callback,
                                    struct evmc_tracer_context* context)