Skip to content

Commit

Permalink
fix(docs): fix linter generation
Browse files Browse the repository at this point in the history
  • Loading branch information
bdeneux committed Jan 12, 2023
1 parent 62e93f7 commit 0ffa36e
Show file tree
Hide file tree
Showing 2 changed files with 198 additions and 12 deletions.
188 changes: 187 additions & 1 deletion docs/proto/logic.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,193 @@

## 📝 Description

Lorem impsus dolor sit amet
This module implements a [Prolog](https://en.wikipedia.org/wiki/Prolog) logic interpreter (go-native) and
its [unification](https://en.wikipedia.org/wiki/Unification_(computer_science))
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:

```prolog
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:

```prolog
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:

```prolog
head.
```

For instance:

```prolog
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:

```prolog
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:

```text
{
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:

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

Gives:

```json
{
"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:

```prolog
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](https://en.wikipedia.org/wiki/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](https://en.wikipedia.org/wiki/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

Expand Down
22 changes: 11 additions & 11 deletions proto/logic/docs.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -33,29 +33,29 @@ description: |
A rule has the following format:
```prolog
head :- body.
```
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:
```prolog
```prolog
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:
```prolog
head.
```
head.
```
For instance:
```prolog
```prolog
father(john, mary). # john is the father of mary.
```
```
#### Variable
Expand Down Expand Up @@ -140,7 +140,7 @@ description: |
chain_id(X). # ask for the chain ID.
```
#### Result
#### Response
The response is an object that contains the following fields:
Expand All @@ -155,7 +155,7 @@ description: |
- `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
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
Expand All @@ -165,7 +165,7 @@ description: |
program.
Keep in mind that he module uses [backtracking](https://en.wikipedia.org/wiki/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](https://en.wikipedia.org/wiki/Backtracking) and searching through possible
attempt to find a solution by [backtracking](https://en.wikipedia.org/wiki/Backtracking) and searching through possible
solutions for an extended period before ultimately being canceled.
## Gas
Expand Down

0 comments on commit 0ffa36e

Please sign in to comment.