Algod: Add experimental endpoint for simulating transactions against a real block evaluator

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

@@ -20,10 +20,10 @@ Each API in `algod.oas2.json`, except for some pre-existing `common` APIs, shoul
 1. Either `public` or `private`. This controls the type of authentication used by the API--the `public` APIs use the
 `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.
+2. The type, or group, of API. This is currently `participating`, `nonparticipating`, `data`, or `experimental`, but
+may expand in the 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. WARNING: This endpoint is experimental and under active development. There are no guarantees in terms of functionality or future support.",
+        "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": {

daemon/algod/api/algod.oas3.yml

@@ -721,6 +721,30 @@
         },
         "description": "Transaction ID of the submission."
       },
+      "SimulationResponse": {
+        "content": {
+          "application/json": {
+            "schema": {
+              "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"
+                }
+              },
+              "required": [
+                "failure-message",
+                "missing-signatures"
+              ],
+              "type": "object"
+            }
+          }
+        },
+        "description": "Result of a transaction group simulation."
+      },
       "StateProofResponse": {
         "content": {
           "application/json": {
@@ -5346,7 +5370,7 @@
             "description": "Unknown Error"
           }
         },
-        "summary": "Broadcasts a raw transaction to the network.",
+        "summary": "Broadcasts a raw transaction or transaction group to the network.",
         "tags": [
           "public",
           "participating"
@@ -5687,6 +5711,99 @@
         ]
       }
     },
+    "/v2/transactions/simulate": {
+      "post": {
+        "operationId": "SimulateTransaction",
+        "requestBody": {
+          "content": {
+            "application/x-binary": {
+              "schema": {
+                "format": "binary",
+                "type": "string"
+              }
+            }
+          },
+          "description": "The byte encoded transaction to simulate",
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "content": {
+              "application/msgpack": {
+                "schema": {
+                  "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"
+                    }
+                  },
+                  "required": [
+                    "failure-message",
+                    "missing-signatures"
+                  ],
+                  "type": "object"
+                }
+              }
+            },
+            "description": "Result of a transaction group simulation."
+          },
+          "400": {
+            "content": {
+              "application/msgpack": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Bad Request - Malformed Algorand transaction"
+          },
+          "401": {
+            "content": {
+              "application/msgpack": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Invalid API Token"
+          },
+          "500": {
+            "content": {
+              "application/msgpack": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Internal Error"
+          },
+          "503": {
+            "content": {
+              "application/msgpack": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Service Temporarily Unavailable"
+          },
+          "default": {
+            "content": {},
+            "description": "Unknown Error"
+          }
+        },
+        "summary": "Simulates a raw transaction or transaction group as it would be evaluated on the network. WARNING: This endpoint is experimental and under active development. There are no guarantees in terms of functionality or future support.",
+        "tags": [
+          "public",
+          "experimental"
+        ],
+        "x-codegen-request-body-name": "rawtxn"
+      }
+    },
     "/versions": {
       "get": {
         "description": "Retrieves the supported API versions, binary build versions, and genesis information.",

daemon/algod/api/server/router.go

@@ -30,6 +30,7 @@ import (
 	"github.com/algorand/go-algorand/daemon/algod/api/server/lib/middlewares"
 	"github.com/algorand/go-algorand/daemon/algod/api/server/v1/routes"
 	v2 "github.com/algorand/go-algorand/daemon/algod/api/server/v2"
+	"github.com/algorand/go-algorand/daemon/algod/api/server/v2/generated/experimental"
 	npprivate "github.com/algorand/go-algorand/daemon/algod/api/server/v2/generated/nonparticipating/private"
 	nppublic "github.com/algorand/go-algorand/daemon/algod/api/server/v2/generated/nonparticipating/public"
 	pprivate "github.com/algorand/go-algorand/daemon/algod/api/server/v2/generated/participating/private"
@@ -112,6 +113,10 @@ func NewRouter(logger logging.Logger, node *node.AlgorandFullNode, shutdown <-ch
 	ppublic.RegisterHandlers(e, &v2Handler, apiAuthenticator)
 	pprivate.RegisterHandlers(e, &v2Handler, adminAuthenticator)
 
+	if node.Config().EnableExperimentalAPI {
+		experimental.RegisterHandlers(e, &v2Handler, apiAuthenticator)
+	}
+
 	return e
 }
 

daemon/algod/api/server/v2/generated/data/data_routes.yml

@@ -11,6 +11,7 @@ output-options:
   - private
   - participating
   - nonparticipating
+  - experimental
   type-mappings:
     integer: uint64
   skip-prune: true