Algod: Replace logic.DebuggerHook with logic.EvalTracer interface

cmd/tealdbg/README.md

@@ -9,6 +9,7 @@
     - [Protocol](#protocol)
     - [Transaction and Transaction Group](#transaction-and-transaction-group)
     - [Balance records](#balance-records)
+    - [Indexer Support](#indexer-support)
     - [Execution mode](#execution-mode)
   - [Chrome DevTools Frontend Features](#chrome-devtools-frontend-features)
     - [Configure the Listener](#configure-the-listener)
@@ -44,7 +45,7 @@ and balance records (see [Setting Debug Context](#setting-debug-context) for det
 
 Remote debugger might be useful for debugging unit tests for TEAL (currently in Golang only) or for hacking **algod** `eval` and breaking on any TEAL evaluation.
 The protocol consist of three REST endpoints and one data structure describing the evaluator state.
-See `WebDebuggerHook` and `TestWebDebuggerManual` in [go-algorand sources](https://github.com/algorand/go-algorand/tree/master/data/transactions/logic) for more details.
+See `WebDebugger` and `TestWebDebuggerManual` in [go-algorand sources](https://github.com/algorand/go-algorand/tree/master/data/transactions/logic) for more details.
 
 ### Frontends
 
@@ -206,13 +207,18 @@ Refer to the [Chrome DevTools debugging](https://developers.google.com/web/tools
 
 The evaluator accepts a new `Debugger` parameter described as the interface:
 ```golang
-type DebuggerHook interface {
+// Debugger is an interface that supports the first version of AVM debuggers.
+// It consists of a set of functions called by eval function during AVM program execution.
+//
+// Deprecated: This interface does not support non-app call or inner transactions. Use EvalTracer
+// instead.
+type Debugger interface {
 	// Register is fired on program creation
-	Register(state *DebugState) error
+	Register(state *DebugState)
 	// Update is fired on every step
-	Update(state *DebugState) error
+	Update(state *DebugState)
 	// Complete is called when the program exits
-	Complete(state *DebugState) error
+	Complete(state *DebugState)
 }
 ```
 If `Debugger` is set the evaluator calls `Register` on creation, `Update` on every step and `Complete` on exit.
@@ -251,13 +257,13 @@ The core calls `SessionEnded` on `Complete` call.
 
 If one needs to debug TEAL in as much real environment as possible then do
 
-1. Add `WebDebuggerHook` to `data/transactions/logic/eval.go`:
+1. Add `WebDebugger` to `data/transactions/logic/eval.go`:
     ```golang
     cx.program = program
 
     // begin new code
     debugURL := os.Getenv("TEAL_DEBUGGER_URL")
-    cx.Debugger = &WebDebuggerHook{URL: debugURL}
+    cx.Debugger = &WebDebugger{URL: debugURL}
     // end new code
 
     if cx.Debugger != nil {

cmd/tealdbg/debugger.go

@@ -26,6 +26,7 @@ import (
 
 	"github.com/algorand/go-algorand/data/basics"
 	"github.com/algorand/go-algorand/data/transactions/logic"
+	"github.com/algorand/go-algorand/logging"
 )
 
 // Notification is sent to the client over their websocket connection
@@ -528,7 +529,7 @@ func (d *Debugger) SaveProgram(
 }
 
 // Register setups new session and notifies frontends if any
-func (d *Debugger) Register(state *logic.DebugState) error {
+func (d *Debugger) Register(state *logic.DebugState) {
 	sid := state.ExecID
 	pcOffset := make(map[int]int, len(state.PCOffset))
 	for _, pco := range state.PCOffset {
@@ -556,12 +557,17 @@ func (d *Debugger) Register(state *logic.DebugState) error {
 
 	// Wait for acknowledgement
 	<-s.acknowledged
-
-	return nil
 }
 
 // Update process state update notifications: pauses or continues as needed
-func (d *Debugger) Update(state *logic.DebugState) error {
+func (d *Debugger) Update(state *logic.DebugState) {
+	err := d.update(state)
+	if err != nil {
+		logging.Base().Errorf("error in Update hook: %s", err.Error())
+	}
+}
+
+func (d *Debugger) update(state *logic.DebugState) error {
 	sid := state.ExecID
 	s, err := d.getSession(sid)
 	if err != nil {
@@ -596,7 +602,14 @@ func (d *Debugger) Update(state *logic.DebugState) error {
 }
 
 // Complete terminates session and notifies frontends if any
-func (d *Debugger) Complete(state *logic.DebugState) error {
+func (d *Debugger) Complete(state *logic.DebugState) {
+	err := d.complete(state)
+	if err != nil {
+		logging.Base().Errorf("error in Complete hook: %s", err.Error())
+	}
+}
+
+func (d *Debugger) complete(state *logic.DebugState) error {
 	sid := state.ExecID
 	s, err := d.getSession(sid)
 	if err != nil {

cmd/tealdbg/debugger_test.go

@@ -102,7 +102,7 @@ func TestDebuggerSimple(t *testing.T) {
 	debugger.AddAdapter(da)
 
 	ep := logic.NewEvalParams(make([]transactions.SignedTxnWithAD, 1), &proto, nil)
-	ep.Debugger = debugger
+	ep.Tracer = logic.MakeEvalTracerDebuggerAdaptor(debugger)
 	ep.SigLedger = logic.NoHeaderLedger{}
 
 	source := `int 0

cmd/tealdbg/local.go

@@ -536,7 +536,7 @@ func (r *LocalRunner) RunAll() error {
 		// ep.Debugger = r.debugger
 		// if ep.Debugger != nil // FALSE
 		if r.debugger != nil {
-			ep.Debugger = r.debugger
+			ep.Tracer = logic.MakeEvalTracerDebuggerAdaptor(r.debugger)
 		}
 	}
 

cmd/tealdbg/remote.go

@@ -26,7 +26,7 @@ import (
 	"github.com/algorand/go-algorand/protocol"
 )
 
-// RemoteHookAdapter provides HTTP transport for WebDebuggerHook
+// RemoteHookAdapter provides HTTP transport for WebDebugger
 type RemoteHookAdapter struct {
 	debugger *Debugger
 }
@@ -38,7 +38,7 @@ func MakeRemoteHook(debugger *Debugger) *RemoteHookAdapter {
 	return r
 }
 
-// Setup adds HTTP handlers for remote WebDebuggerHook
+// Setup adds HTTP handlers for remote WebDebugger
 func (rha *RemoteHookAdapter) Setup(router *mux.Router) {
 	router.HandleFunc("/exec/register", rha.registerHandler).Methods("POST")
 	router.HandleFunc("/exec/update", rha.updateHandler).Methods("POST")
@@ -59,11 +59,7 @@ func (rha *RemoteHookAdapter) registerHandler(w http.ResponseWriter, r *http.Req
 	}
 
 	// Register, and wait for user to acknowledge registration
-	err = rha.debugger.Register(&state)
-	if err != nil {
-		w.WriteHeader(http.StatusBadRequest)
-		return
-	}
+	rha.debugger.Register(&state)
 
 	// Proceed!
 	w.WriteHeader(http.StatusOK)
@@ -78,7 +74,7 @@ func (rha *RemoteHookAdapter) updateHandler(w http.ResponseWriter, r *http.Reque
 	}
 
 	// Ask debugger to process and wait to continue
-	err = rha.debugger.Update(&state)
+	err = rha.debugger.update(&state)
 	if err != nil {
 		w.WriteHeader(http.StatusBadRequest)
 		return
@@ -96,7 +92,7 @@ func (rha *RemoteHookAdapter) completeHandler(w http.ResponseWriter, r *http.Req
 	}
 
 	// Ask debugger to process and wait to continue
-	err = rha.debugger.Complete(&state)
+	err = rha.debugger.complete(&state)
 	if err != nil {
 		w.WriteHeader(http.StatusBadRequest)
 		return

config/localTemplate.go

@@ -467,6 +467,10 @@ type Local struct {
 	// 0x01 (txFilterRawMsg) - check for raw tx message duplicates
 	// 0x02 (txFilterCanonical) - check for canonical tx group duplicates
 	TxIncomingFilteringFlags uint32 `version[26]:"1"`
+
+	// EnableExperimentalAPI enables experimental API endpoint. Note that these endpoints have no
+	// guarantees in terms of functionality or future support.
+	EnableExperimentalAPI bool `version[26]:"false"`
 }
 
 // DNSBootstrapArray returns an array of one or more DNS Bootstrap identifiers

config/local_defaults.go

@@ -59,6 +59,7 @@ var defaultLocal = Local{
 	EnableBlockServiceFallbackToArchiver:       true,
 	EnableCatchupFromArchiveServers:            false,
 	EnableDeveloperAPI:                         false,
+	EnableExperimentalAPI:                      false,
 	EnableGossipBlockService:                   true,
 	EnableIncomingMessageFilter:                false,
 	EnableLedgerService:                        false,

crypto/merklesignature/committablePublicKeys.go

@@ -34,7 +34,7 @@ type (
 		keyLifetime uint64
 	}
 
-	// CommittablePublicKey  is used to create a binary representation of public keys in the merkle
+	// CommittablePublicKey is used to create a binary representation of public keys in the merkle
 	// signature scheme.
 	CommittablePublicKey struct {
 		VerifyingKey crypto.FalconVerifier

daemon/algod/api/Makefile

@@ -2,7 +2,7 @@ GOPATH	:= $(shell go env GOPATH)
 GOPATH1	:= $(firstword $(subst :, ,$(GOPATH)))
 
 # `make all` or just `make` should be appropriate for dev work
-all:	server/v2/generated/model/types.go server/v2/generated/nonparticipating/public/routes.go server/v2/generated/nonparticipating/private/routes.go server/v2/generated/participating/public/routes.go server/v2/generated/participating/private/routes.go server/v2/generated/data/routes.go
+all:	server/v2/generated/model/types.go server/v2/generated/nonparticipating/public/routes.go server/v2/generated/nonparticipating/private/routes.go server/v2/generated/participating/public/routes.go server/v2/generated/participating/private/routes.go server/v2/generated/data/routes.go server/v2/generated/experimental/routes.go
 
 # `make generate` should be able to replace old `generate.sh` script and be appropriate for build system use
 generate:	oapi-codegen all
@@ -23,6 +23,9 @@ server/v2/generated/participating/private/routes.go:	algod.oas3.yml
 server/v2/generated/data/routes.go:	algod.oas3.yml
 	$(GOPATH1)/bin/oapi-codegen -config ./server/v2/generated/data/data_routes.yml algod.oas3.yml
 
+server/v2/generated/experimental/routes.go:	algod.oas3.yml
+	$(GOPATH1)/bin/oapi-codegen -config ./server/v2/generated/experimental/experimental_routes.yml algod.oas3.yml
+
 server/v2/generated/model/types.go:	algod.oas3.yml
 	$(GOPATH1)/bin/oapi-codegen -config ./server/v2/generated/model/model_types.yml algod.oas3.yml
 

daemon/algod/api/README.md

@@ -21,9 +21,9 @@ Each API in `algod.oas2.json`, except for some pre-existing `common` APIs, shoul
 `algod.token` token, while the `private` APIs use the admin token, found in `algod.admin.token` within the algod data
 directory.
 2. The type, or group, of API. This is currently `participating`, `nonparticipating`, or `data`, but may expand in the
-future to encompass different sets of APIs such as `experimental` APIs. Additional APIs should be added to one of the
-existing sets of tags based on its use case--unless you intend to create a new group in which case you will need to 
-additionally ensure your new APIs are registered.
+future to encompass different sets of APIs. Additional APIs should be added to one of the existing sets of tags based
+on its use case--unless you intend to create a new group in which case you will need to additionally ensure your new
+APIs are registered.
 
 For backwards compatibility, the default set of APIs registered will always be `participating` and `nonparticipating`
 APIs.
@@ -38,6 +38,8 @@ participation keys, the agreement service, etc.
   * A special set of APIs which require manipulating the node state in order to provide additional data about the node state
 at some predefined granularity. For example, SetSyncRound and GetLedgerStateDelta used together control and expose StateDelta objects
 containing per-round ledger differences that get compacted when actually written to the ledger DB.
+* `experimental`
+  * APIs which are still in development and not ready to be generally released.
 
 ## What codegen tool is used?
 

daemon/algod/api/algod.oas2.json

@@ -1157,7 +1157,7 @@
         "schemes": [
           "http"
         ],
-        "summary": "Broadcasts a raw transaction to the network.",
+        "summary": "Broadcasts a raw transaction or transaction group to the network.",
         "operationId": "RawTransaction",
         "parameters": [
           {
@@ -1205,6 +1205,69 @@
         }
       }
     },
+    "/v2/transactions/simulate": {
+      "post": {
+        "tags": [
+          "public",
+          "experimental"
+        ],
+        "consumes": [
+          "application/x-binary"
+        ],
+        "produces": [
+          "application/msgpack"
+        ],
+        "schemes": [
+          "http"
+        ],
+        "summary": "Simulates a raw transaction or transaction group as it would be evaluated on the network.",
+        "operationId": "SimulateTransaction",
+        "parameters": [
+          {
+            "description": "The byte encoded transaction to simulate",
+            "name": "rawtxn",
+            "in": "body",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "binary"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "$ref": "#/responses/SimulationResponse"
+          },
+          "400": {
+            "description": "Bad Request - Malformed Algorand transaction",
+            "schema": {
+              "$ref": "#/definitions/ErrorResponse"
+            }
+          },
+          "401": {
+            "description": "Invalid API Token",
+            "schema": {
+              "$ref": "#/definitions/ErrorResponse"
+            }
+          },
+          "500": {
+            "description": "Internal Error",
+            "schema": {
+              "$ref": "#/definitions/ErrorResponse"
+            }
+          },
+          "503": {
+            "description": "Service Temporarily Unavailable",
+            "schema": {
+              "$ref": "#/definitions/ErrorResponse"
+            }
+          },
+          "default": {
+            "description": "Unknown Error"
+          }
+        }
+      }
+    },
     "/v2/transactions/params": {
       "get": {
         "tags": [
@@ -4128,6 +4191,29 @@
         }
       }
     },
+    "SimulationResponse": {
+      "description": "Result of a transaction group simulation.",
+      "tags": [
+        "experimental"
+      ],
+      "schema": {
+        "type": "object",
+        "required": [
+          "failure-message",
+          "missing-signatures"
+        ],
+        "properties": {
+          "failure-message": {
+            "description": "\\[fm\\] Failure message, if the transaction would have failed during a live broadcast.",
+            "type": "string"
+          },
+          "missing-signatures": {
+            "description": "\\[ms\\] Whether any transactions would have failed during a live broadcast because they were missing signatures.",
+            "type": "boolean"
+          }
+        }
+      }
+    },
     "SupplyResponse": {
       "description": "Supply represents the current supply of MicroAlgos in the system.",
       "schema": {