Skip to main content
Version: v4.0.0

Protobuf Documentation

📝 Description

This module implements a Prolog logic interpreter (go-native) and its unification algorithm to evaluate logical expressions against the current state of the blockchain.

This distinctive module allows for the creation of advanced, goal-oriented queries and logical systems that can be applied to a wide range of use cases, while still maintaining the determinism and predictability of blockchain technology. It also features a collection of predefined, blockchain-specific predicates that can be used to access information about the state of the blockchain.

Concepts

Program

A program is a text that is parsed and compiled by the interpreter. A program is composed of a set of predicates, which are defined by the user and can be used to express the desired query logic.

Predicate

A predicate is a statement that describes a relationship between one or more variables or constants. A predicate consists of a name followed by zero or more arguments.

Rule & Fact

A rule is a statement that describes a relationship between one or more variables or constants, similar to a predicate. However, unlike a predicate, a rule also specifies one or more conditions that must be true in order for the relationship described by the rule to hold.

A rule has the following format:

head :- body.

The symbol :- is called the "if-then" operator, and it means that the relationship described in the head of the rule holds only if the conditions in the body are true.

For example:

grandfather(X,Y) :- father(X,Z), father(Z,Y). # X is the grandfather of Y if X is the father of Z and Z is the father of Y.

A fact is a special type of rule that has no body (with no :- and no conditions). A fact has the following format:

head.

For instance:

father(john, mary). # john is the father of mary.

Variable

A variable is a predicate argument that is used as a placeholder for a value. It can represent any type of data, such as numbers, strings, or lists.

Variables are denoted by a name that starts with an uppercase letter, for example X or Foo.

For instance:

father(X, mary). # ask for all X that are the father of mary.

Query

A query is a statement used to retrieve information from the blockchain. It can be sent against a program, but this is optional. The interpreter evaluates the query and returns the result to the caller. Queries can be submitted to a module using the Ask message.

Ask

The Ask message is used to submit a query to the module. It has the following format:

{
string Program
string Query
}

The Program field is optional. If it is not specified, the query is just evaluated against the current state of the blockchain. If it is specified, the query is evaluated against the program that is passed as an argument.

For instance:

{
Program: "father(john, mary)."
Query: "father(X, mary)."
}

Gives:

{
"height": "7235",
"gas_used": "9085",
"answer": {
"success": true,
"has_more": false,
"variables": [
"X"
],
"results": [
{
"substitutions": [
{
"variable": "X",
"term": {
"name": "john",
"arguments": []
}
}
]
}
]
}
}

The logic module supports chain-specific predicates that can be used to query the state of the blockchain. For example, the chain_id predicate can be used to retrieve the chain ID of the current blockchain. Several other predicates are available, such as block_height, block_time... Please refer to the go documentation for the full list of available predicates.

For instance:

chain_id(X). # ask for the chain ID.

Response

The response is an object that contains the following fields:

  • height: the height of the block at which the query was evaluated.
  • gas_used: the amount of gas used to evaluate the query.
  • answer: the result of the query. It is an object that contains the following fields:
    • success: a boolean that indicates whether the query was successful or not. Successful means that solutions were found, i.e. the query was satisfiable.
    • has_more: a boolean that indicates whether there are more results to be retrieved. It's just informative since no more results can be retrieved.
    • variables: an array of strings that contains the names of the variables that were used in the query.
    • results: an array of objects that contains the results of the query. Each result is an object that contains the following fields:
      • substitutions: an array of objects that contains the substitutions that were made to satisfy the query. A substitution is a set of variable-value pairs that is used to replace variables with constants. A substitution is the result of unification. A substitution is used to replace variables with constants when evaluating a rule.

Performance

The performance of the logic module is closely tied to the complexity of the query and the size of the program. To optimize performance, especially in a constrained environment like the blockchain, it is important to minimize the size of the program. Keep in mind that he module uses backtracking to search for solutions, making it most effective when used for queries that are satisfiable. Indeed, if the query is not satisfiable, the module will attempt to find a solution by backtracking and searching through possible solutions for an extended period before ultimately being canceled.

Gas

The Ask message incurs gas consumption, which is calculated as the sum of the gas used to evaluate each predicate during the query evaluation process. Each predicate has a fixed gas cost that is based on its complexity.

While querying the module does not require any fees, the use of gas serves as a mechanism to limit the size and complexity of the query, ensuring optimal performance and fairness.

Security

The logic module is a deterministic program that is executed in a sandboxed environment and does not have the ability to submit transactions or make changes to the blockchain's state. It is therefore safe to use.

To control the cpu and memory usage of the module, the module is limited by several different mechanisms:

  • max_gas: the maximum amount of gas that can be used to evaluate a query.
  • max_size: the maximum size of the program that can be evaluated.
  • max_result_count: the maximum number of results that can be returned by a query.

Additional limitations are being considered for the future, such as restricting the number of variables that can be utilized within a query, or limiting the depth of the backtracking algorithm.

Table of Contents

Top

logic/v1beta/params.proto

Interpreter

Interpreter defines the various parameters for the interpreter.

FieldTypeLabelDescription
registered_predicatesstringrepeatedregistered_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.
bootstrapstringbootstrap specifies the initial program to run when booting the logic interpreter. If not specified, the default boot sequence will be executed.

Limits

Limits defines the limits of the logic module.

FieldTypeLabelDescription
max_gasstringmax_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. nil value remove max gas limitation.
max_sizestringmax_size specifies the maximum size, in bytes, that is accepted for a program. nil value remove size limitation.
max_result_countstringmax_result_count specifies the maximum number of results that can be requested for a query. nil value remove max result count limitation.

Params

Params defines all the configuration parameters of the "logic" module.

FieldTypeLabelDescription
interpreterInterpreterInterpreter specifies the parameter for the logic interpreter.
limitsLimitsLimits 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.

Top

logic/v1beta/genesis.proto

GenesisState

GenesisState defines the logic module's genesis state.

FieldTypeLabelDescription
paramsParamsThe state parameters for the logic module.

Top

logic/v1beta/types.proto

Answer

Answer represents the answer to a logic query.

FieldTypeLabelDescription
successboolresult is the result of the query.
has_moreboolhas_more specifies if there are more solutions than the ones returned.
variablesstringrepeatedvariables represent all the variables in the query.
resultsResultrepeatedresults represent all the results of the query.

Result

Result represents the result of a query.

FieldTypeLabelDescription
substitutionsSubstitutionrepeatedsubstitutions represent all the substitutions made to the variables in the query to obtain the answer.

Substitution

Substitution represents a substitution made to the variables in the query to obtain the answer.

FieldTypeLabelDescription
variablestringvariable is the name of the variable.
termTermterm is the term that the variable is substituted with.

Term

Term is the representation of a piece of data and can be a constant, a variable, or an atom.

FieldTypeLabelDescription
namestringname is the name of the term.
argumentsTermrepeatedarguments are the arguments of the term, which can be constants, variables, or atoms.

Top

logic/v1beta/query.proto

QueryServiceAskRequest

QueryServiceAskRequest is request type for the QueryService/Ask RPC method.

FieldTypeLabelDescription
programstringprogram is the logic program to be queried.
querystringquery is the query string to be executed.

QueryServiceAskResponse

QueryServiceAskResponse is response type for the QueryService/Ask RPC method.

FieldTypeLabelDescription
heightuint64height is the block height at which the query was executed.
gas_useduint64gas_used is the amount of gas used to execute the query.
answerAnsweranswer is the answer to the query.

QueryServiceParamsRequest

QueryServiceParamsRequest is request type for the QueryService/Params RPC method.

QueryServiceParamsResponse

QueryServiceParamsResponse is response type for the QueryService/Params RPC method.

FieldTypeLabelDescription
paramsParamsparams holds all the parameters of this module.

QueryService

QueryService defines the gRPC querier service.

Method NameRequest TypeResponse TypeDescriptionHTTP VerbEndpoint
ParamsQueryServiceParamsRequestQueryServiceParamsResponseParams queries all parameters for the logic module.GET/okp4/okp4d/logic/params
AskQueryServiceAskRequestQueryServiceAskResponseAsk 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/ask

Top

logic/v1beta/tx.proto

MsgService

MsgService defines the service for the logic module. Do nothing for now as the service is without any side effects.

Method NameRequest TypeResponse TypeDescriptionHTTP VerbEndpoint

Scalar Value Types

.proto TypeNotesC++JavaPythonGoC#PHPRuby
doubledoubledoublefloatfloat64doublefloatFloat
floatfloatfloatfloatfloat32floatfloatFloat
int32Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.int32intintint32intintegerBignum or Fixnum (as required)
int64Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.int64longint/longint64longinteger/stringBignum
uint32Uses variable-length encoding.uint32intint/longuint32uintintegerBignum or Fixnum (as required)
uint64Uses variable-length encoding.uint64longint/longuint64ulonginteger/stringBignum or Fixnum (as required)
sint32Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.int32intintint32intintegerBignum or Fixnum (as required)
sint64Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.int64longint/longint64longinteger/stringBignum
fixed32Always four bytes. More efficient than uint32 if values are often greater than 2^28.uint32intintuint32uintintegerBignum or Fixnum (as required)
fixed64Always eight bytes. More efficient than uint64 if values are often greater than 2^56.uint64longint/longuint64ulonginteger/stringBignum
sfixed32Always four bytes.int32intintint32intintegerBignum or Fixnum (as required)
sfixed64Always eight bytes.int64longint/longint64longinteger/stringBignum
boolboolbooleanbooleanboolboolbooleanTrueClass/FalseClass
stringA string must always contain UTF-8 encoded or 7-bit ASCII text.stringStringstr/unicodestringstringstringString (UTF-8)
bytesMay contain any arbitrary sequence of bytes.stringByteStringstr[]byteByteStringstringString (ASCII-8BIT)