Merge pull request #221 from okp4/feat/logic-spec

📜 Logic module specification

Makefile

@@ -99,13 +99,14 @@ ifeq ($(SHELL_NAME),Darwin)
     SED_FLAG := ""
 endif
 
-.PHONY: all lint lint-go build build-go help
-
+.PHONY: all
 all: help
 
 ## Lint:
+.PHONY: lint
 lint: lint-go lint-proto ## Lint all available linters
 
+.PHONY: lint-go
 lint-go: ## Lint go source code
 	@echo "${COLOR_CYAN}🔍 Inspecting go source code${COLOR_RESET}"
 	@docker run --rm \
@@ -114,6 +115,7 @@ lint-go: ## Lint go source code
   		${DOCKER_IMAGE_GOLANG_CI} \
   		golangci-lint run -v
 
+.PHONY: lint-proto
 lint-proto: ## Lint proto files
 	@echo "${COLOR_CYAN}🔍️ lint proto${COLOR_RESET}"
 	@docker run --rm \
@@ -122,10 +124,18 @@ lint-proto: ## Lint proto files
   		-w /proto \
   		${DOCKER_IMAGE_BUF} \
   		lint proto -v
+	@docker run --rm \
+ 		-v ${HOME}/.cache:/root/.cache \
+   		-v `pwd`:/proto \
+   		-w /proto \
+   		${DOCKER_IMAGE_BUF} \
+   		format -d --exit-code
 
 ## Format:
+.PHONY: format
 format: format-go ## Run all available formatters
 
+.PHONY: format-go
 format-go: ## Format go files
 	@echo "${COLOR_CYAN}📐 Formatting go source code${COLOR_RESET}"
 	@docker run --rm \
@@ -135,9 +145,21 @@ format-go: ## Format go files
   		sh -c \
 		"go install mvdan.cc/[email protected]; gofumpt -w -l ."
 
+.PHONY: format-proto
+format-proto: ## Format proto files
+	@echo "${COLOR_CYAN}📐 Formatting proto files${COLOR_RESET}"
+	@docker run --rm \
+		-v ${HOME}/.cache:/root/.cache \
+  		-v `pwd`:/proto \
+  		-w /proto \
+  		${DOCKER_IMAGE_BUF} \
+  		format -w
+
 ## Build:
+.PHONY: build
 build: build-go ## Build all available artefacts (executable, docker image, etc.)
 
+.PHONY: build-go
 build-go: ## Build node executable for the current environment (default build)
 	@echo "${COLOR_CYAN} 🏗️ Building project ${COLOR_RESET}${CMD_ROOT}${COLOR_CYAN}${COLOR_RESET} into ${COLOR_YELLOW}${DIST_FOLDER}${COLOR_RESET}"
 	@$(call build-go,"","",${DIST_FOLDER}/${BINARY_NAME})
@@ -165,13 +187,16 @@ $(ENVIRONMENTS_TARGETS):
 
 
 ## Install:
+.PHONY: install
 install: ## Install node executable
 	@echo "${COLOR_CYAN} 🚚 Installing project ${BINARY_NAME}${COLOR_RESET}"
 	@go install ${BUILD_FLAGS} ${CMD_ROOT}
 
 ## Test:
+.PHONY: test
 test: test-go ## Pass all the tests
 
+.PHONY: test-go
 test-go: build ## Pass the test for the go source code
 	@echo "${COLOR_CYAN} 🧪 Passing go tests${COLOR_RESET}"
 	@go test -v -covermode=count -coverprofile ./target/coverage.out ./...
@@ -218,11 +243,16 @@ chain-stop: ## Stop the blockchain
 	@killall okp4d
 
 ## Clean:
+.PHONY: clean
 clean: ## Remove all the files from the target folder
 	@echo "${COLOR_CYAN} 🗑 Cleaning folder $(TARGET_FOLDER)${COLOR_RESET}"
 	@rm -rf $(TARGET_FOLDER)/
 
 ## Proto:
+.PHONY: proto
+proto: proto-format lint-proto proto-build proto-gen doc-proto ## Generate all resources for proto files (go, doc, etc.)
+
+.PHONY: proto-format
 proto-format: ## Format Protobuf files
 	@echo "${COLOR_CYAN} 📐 Formatting Protobuf files${COLOR_RESET}"
 	@docker run --rm \
@@ -232,6 +262,7 @@ proto-format: ## Format Protobuf files
     		${DOCKER_IMAGE_BUF} \
     		format -w -v
 
+.PHONY: proto-build
 proto-build: ## Build all Protobuf files
 	@echo "${COLOR_CYAN} 🔨️Build Protobuf files${COLOR_RESET}"
 	@docker run --rm \
@@ -241,6 +272,7 @@ proto-build: ## Build all Protobuf files
 		${DOCKER_IMAGE_BUF} \
 		build proto -v
 
+.PHONY: proto-gen
 proto-gen: proto-build ## Generate all the code from the Protobuf files
 	@echo "${COLOR_CYAN} 📝 Generating code from Protobuf files${COLOR_RESET}"
 	@docker run --rm \
@@ -287,6 +319,7 @@ doc-command: ## Generate markdown documentation for the command
 	  ${DOCKER_IMAGE_MARKDOWNLINT} -f $$OUT_FOLDER
 
 ## Release:
+.PHONY: release-assets
 release-assets: release-binary-all release-checksums ## Generate release assets
 
 release-binary-all: $(RELEASE_TARGETS)
@@ -322,6 +355,7 @@ ensure-buildx-builder:
 	docker buildx create --name ${DOCKER_BUILDX_BUILDER}
 
 ## Help:
+.PHONY: help
 help: ## Show this help.
 	@echo ''
 	@echo 'Usage:'

README.md

@@ -140,6 +140,7 @@ Targets:
   Format:
     format              Run all available formatters
     format-go           Format go files
+    format-proto        Format proto files
   Build:
     build               Build all available artefacts (executable, docker image, etc.)
     build-go            Build node executable for the current environment (default build)
@@ -155,6 +156,7 @@ Targets:
   Clean:
     clean               Remove all the files from the target folder
   Proto:
+    proto               Generate all resources for proto files (go, doc, etc.)
     proto-format        Format Protobuf files
     proto-build         Build all Protobuf files
     proto-gen           Generate all the code from the Protobuf files

docs/proto/logic.md

@@ -7,14 +7,24 @@
 ## Table of Contents
 
 - [logic/v1beta/params.proto](#logic/v1beta/params.proto)
+  - [Interpreter](#logic.v1beta.Interpreter)
+  - [Limits](#logic.v1beta.Limits)
   - [Params](#logic.v1beta.Params)
 
 - [logic/v1beta/genesis.proto](#logic/v1beta/genesis.proto)
   - [GenesisState](#logic.v1beta.GenesisState)
 
+- [logic/v1beta/types.proto](#logic/v1beta/types.proto)
+  - [Answer](#logic.v1beta.Answer)
+  - [Result](#logic.v1beta.Result)
+  - [Substitution](#logic.v1beta.Substitution)
+  - [Term](#logic.v1beta.Term)
+
 - [logic/v1beta/query.proto](#logic/v1beta/query.proto)
   - [QueryServiceParamsRequest](#logic.v1beta.QueryServiceParamsRequest)
   - [QueryServiceParamsResponse](#logic.v1beta.QueryServiceParamsResponse)
+  - [QueryServiceQueryRequest](#logic.v1beta.QueryServiceQueryRequest)
+  - [QueryServiceQueryResponse](#logic.v1beta.QueryServiceQueryResponse)
 
   - [QueryService](#logic.v1beta.QueryService)
 
@@ -28,15 +38,39 @@
 
 ## logic/v1beta/params.proto
 
+<a name="logic.v1beta.Interpreter"></a>
+
+### Interpreter
+
+Interpreter defines the various parameters for the interpreter.
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| `registered_predicates` | [string](#string) | repeated | registered_predicates specifies the list of registered predicates/operators, in the form of: `<predicate_name>/<arity>`. For instance: `findall/3`. If not specified, the default set of predicates/operators will be registered. |
+| `bootstrap` | [string](#string) |  | bootstrap specifies the initial program to run when booting the logic interpreter. If not specified, the default boot sequence will be executed. |
+
+<a name="logic.v1beta.Limits"></a>
+
+### Limits
+
+Limits defines the limits of the logic module.
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| `max_gas` | [uint64](#uint64) |  | max_gas specifies the maximum amount of computing power, measured in "gas," that is allowed to be consumed when executing a request by the interpreter. The interpreter calculates the gas consumption based on the number and type of operations that are executed, as well as, in some cases, the complexity of the processed data. |
+| `max_size` | [uint32](#uint32) |  | max_size specifies the maximum size, in bytes, that is accepted for a program. |
+| `max_result_count` | [uint32](#uint32) |  | max_result_count specifies the maximum number of results that can be requested for a query. |
+
 <a name="logic.v1beta.Params"></a>
 
 ### Params
 
-Params defines the parameters for the module.
+Params defines all the configuration parameters of the "logic" module.
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| `foo` | [string](#string) |  | foo represents a metasyntactic variable for testing purposes. |
+| `interpreter` | [Interpreter](#logic.v1beta.Interpreter) |  | Interpreter specifies the parameter for the logic interpreter. |
+| `limits` | [Limits](#logic.v1beta.Limits) |  | Limits defines the limits of the logic module. The limits are used to prevent the interpreter from running for too long. If the interpreter runs for too long, the execution will be aborted. |
 
  [//]: # (end messages)
 
@@ -69,6 +103,64 @@ GenesisState defines the logic module's genesis state.
 
  [//]: # (end services)
 
+<a name="logic/v1beta/types.proto"></a>
+<p align="right"><a href="#top">Top</a></p>
+
+## logic/v1beta/types.proto
+
+<a name="logic.v1beta.Answer"></a>
+
+### Answer
+
+Answer represents the answer to a logic query.
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| `success` | [bool](#bool) |  | result is the result of the query. |
+| `has_more` | [bool](#bool) |  | has_more specifies if there are more solutions than the ones returned. |
+| `variables` | [string](#string) | repeated | variables represent all the variables in the query. |
+| `results` | [Result](#logic.v1beta.Result) | repeated | results represent all the results of the query. |
+
+<a name="logic.v1beta.Result"></a>
+
+### Result
+
+Result represents the result of a query.
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| `substitutions` | [Substitution](#logic.v1beta.Substitution) | repeated | substitutions represent all the substitutions made to the variables in the query to obtain the answer. |
+
+<a name="logic.v1beta.Substitution"></a>
+
+### Substitution
+
+Substitution represents a substitution made to the variables in the query to obtain the answer.
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| `variable` | [string](#string) |  | variable is the name of the variable. |
+| `term` | [Term](#logic.v1beta.Term) |  | term is the term that the variable is substituted with. |
+
+<a name="logic.v1beta.Term"></a>
+
+### Term
+
+Term is the representation of a piece of data and can be a constant, a variable, or an atom.
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| `name` | [string](#string) |  | name is the name of the term. |
+| `arguments` | [Term](#logic.v1beta.Term) | repeated | arguments are the arguments of the term, which can be constants, variables, or atoms. |
+
+ [//]: # (end messages)
+
+ [//]: # (end enums)
+
+ [//]: # (end HasExtensions)
+
+ [//]: # (end services)
+
 <a name="logic/v1beta/query.proto"></a>
 <p align="right"><a href="#top">Top</a></p>
 
@@ -90,6 +182,29 @@ QueryServiceParamsResponse is response type for the QueryService/Params RPC meth
 | ----- | ---- | ----- | ----------- |
 | `params` | [Params](#logic.v1beta.Params) |  | params holds all the parameters of this module. |
 
+<a name="logic.v1beta.QueryServiceQueryRequest"></a>
+
+### QueryServiceQueryRequest
+
+QueryServiceQueryRequest is request type for the QueryService/Query RPC method.
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| `program` | [string](#string) |  | program is the logic program to be queried. |
+| `query` | [string](#string) |  | query is the query string to be executed. |
+
+<a name="logic.v1beta.QueryServiceQueryResponse"></a>
+
+### QueryServiceQueryResponse
+
+QueryServiceQueryResponse is response type for the QueryService/Query RPC method.
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| `height` | [uint64](#uint64) |  | height is the block height at which the query was executed. |
+| `gas_used` | [uint64](#uint64) |  | gas_used is the amount of gas used to execute the query. |
+| `answer` | [Answer](#logic.v1beta.Answer) |  | answer is the answer to the query. |
+
  [//]: # (end messages)
 
  [//]: # (end enums)
@@ -104,7 +219,8 @@ QueryService defines the gRPC querier service.
 
 | Method Name | Request Type | Response Type | Description | HTTP Verb | Endpoint |
 | ----------- | ------------ | ------------- | ------------| ------- | -------- |
-| `Params` | [QueryServiceParamsRequest](#logic.v1beta.QueryServiceParamsRequest) | [QueryServiceParamsResponse](#logic.v1beta.QueryServiceParamsResponse) | Parameters queries the parameters of the module. | GET|/okp4/okp4d/logic/params|
+| `Params` | [QueryServiceParamsRequest](#logic.v1beta.QueryServiceParamsRequest) | [QueryServiceParamsResponse](#logic.v1beta.QueryServiceParamsResponse) | Params queries all parameters for the logic module. | GET|/okp4/okp4d/logic/params|
+| `Query` | [QueryServiceQueryRequest](#logic.v1beta.QueryServiceQueryRequest) | [QueryServiceQueryResponse](#logic.v1beta.QueryServiceQueryResponse) | Query executes a logic query and returns the solutions found. Since the query is without any side-effect, the query is not executed in the context of a transaction and no fee is charged for this, but the execution is constrained by the current limits configured in the module. | GET|/okp4/okp4d/logic/query|
 
  [//]: # (end services)
 
@@ -123,7 +239,8 @@ QueryService defines the gRPC querier service.
 
 ### MsgService
 
-Msg defines the Msg service.
+MsgService defines the service for the logic module.
+Do nothing for now as the service is without any side effects.
 
 | Method Name | Request Type | Response Type | Description | HTTP Verb | Endpoint |
 | ----------- | ------------ | ------------- | ------------| ------- | -------- |

proto/logic/v1beta/params.proto

@@ -6,10 +6,57 @@ import "gogoproto/gogo.proto";
 
 option go_package = "github.com/okp4/okp4d/x/logic/types";
 
-// Params defines the parameters for the module.
+// Params defines all the configuration parameters of the "logic" module.
 message Params {
   option (gogoproto.goproto_stringer) = false;
 
-  // foo represents a metasyntactic variable for testing purposes.
-  string foo = 1 [(gogoproto.moretags) = "yaml:\"foo\""];
+  // Interpreter specifies the parameter for the logic interpreter.
+  Interpreter interpreter = 1 [
+    (gogoproto.nullable) = false,
+    (gogoproto.moretags) = "yaml:\"interpreter\""
+  ];
+
+  // Limits defines the limits of the logic module.
+  // The limits are used to prevent the interpreter from running for too long.
+  // If the interpreter runs for too long, the execution will be aborted.
+  Limits limits = 2 [
+    (gogoproto.nullable) = false,
+    (gogoproto.moretags) = "yaml:\"limits\""
+  ];
+}
+
+// Limits defines the limits of the logic module.
+message Limits {
+  option (gogoproto.goproto_stringer) = true;
+
+  // max_gas specifies the maximum amount of computing power, measured in "gas," that is allowed to be consumed when
+  // executing a request by the interpreter. The interpreter calculates the gas consumption based on the number and type
+  // of operations that are executed, as well as, in some cases, the complexity of the processed data.
+  uint64 max_gas = 1 [(gogoproto.moretags) = "yaml:\"max_gas\",omitempty"];
+
+  // max_size specifies the maximum size, in bytes, that is accepted for a program.
+  uint32 max_size = 3 [(gogoproto.moretags) = "yaml:\"max_size\""];
+
+  // max_result_count specifies the maximum number of results that can be requested for a query.
+  uint32 max_result_count = 2 [(gogoproto.moretags) = "yaml:\"max_result_count\""];
+}
+
+// Interpreter defines the various parameters for the interpreter.
+message Interpreter {
+  option (gogoproto.goproto_stringer) = true;
+
+  // registered_predicates specifies the list of registered predicates/operators, in the form of: `<predicate_name>/<arity>`.
+  // For instance: `findall/3`.
+  // If not specified, the default set of predicates/operators will be registered.
+  repeated string registered_predicates = 1 [
+    (gogoproto.nullable) = true,
+    (gogoproto.moretags) = "yaml:\"registered_predicates\""
+  ];
+
+  // bootstrap specifies the initial program to run when booting the logic interpreter.
+  // If not specified, the default boot sequence will be executed.
+  string bootstrap = 2 [
+    (gogoproto.nullable) = true,
+    (gogoproto.moretags) = "yaml:\"bootstrap\""
+  ];
 }