## 1. Project Overview & Quickstart (IBAX-io/about-the-platform)
# about-the-platform
Open-source repository IBAX-io/about-the-platform
### Repository Details
- **Repository:** [IBAX-io/about-the-platform](https://github.com/IBAX-io/about-the-platform)
- **Primary Language:** Code
*Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.*
## 2. Official Technical Reference & Guides (IBAX-io/docs)
## File: README.md
# IBAX documentation
This website is built using [Docusaurus 3](https://docusaurus.io/), a modern
static website generator.
### Installation
```
$ yarn
```
### Local Development
```
$ yarn start
```
This command starts a local development server and opens up a browser window.
Most changes are reflected live without having to restart the server.
### Build
```
$ yarn build
```
This command generates static content into the `build` directory and can be
served using any static contents hosting service.
### Local development server
This command starts the Docusaurus local development server and opens up a
browser window.
```
$ yarn serve
```
---
## File: docs/needle/intro.md
---
sidebar_position: 1
---
# Introduction
The Needle language includes a set of functions, operators and structures, which
can realize data algorithm processing and database operations. it
general-purpose programming language that is concise, expressive, and efficient.
It is designed to be a language that is easy to read and write, and is suitable
for a wide range of DApps developed of smart contract.
This repository can be found [here](https://github.com/IBAX-io/needle).
- [Specification](/needle/spec)
---
## File: docs/needle/spec.md
---
sidebar_position: 2
title: Specification
toc_min_heading_level: 2
toc_max_heading_level: 4
---
# Needle Specification {#needle-specification}
The Needle Specification is a formal description of the Needle language. It is
intended to be a reference for developers who want to understand the language in
detail.
It is a statically-typed language with a syntax that is familiar to developers
who have experience with golang.
## File Structure {#file-structure}
In Needle language, the main code block structure includes
[Smart Contract](#spec-contract), [Data](#spec-data),
[Function](#spec-function), [Settings](#spec-settings).
### Smart Contract {#spec-contract}
Use the `contract` keyword to declare a smart contract, followed by the name of
the smart contract, and its content must be enclosed in curly braces.
> `ContractStmt` = "contract" [Identifier](#spec-identifier)
> [CodeBlockStmt](#spec-codeblock).
Smart contract structure has three main parts: [Data](#spec-data),
[Settings](#spec-settings), [Function](#spec-function).
```go
contract Name {
data{}
settings{}
func name(){}
}
```
### Data {#spec-data}
Use `data` keyword partially describes the smart contract data input as well as
the received form parameters. The `optional` indicates that the parameter is
optional and not required.
> `DataStmt` = `"data"` `"{"` { `ParamSign` } `"}"` .
>
> `ParamSign` = [Identifier](#spec-identifier) [Typename](#spec-typename) [
> `Tag` ] .
>
> `Tag` = `"optional"` .
use the symbol `$` to get the corresponding variable value, it must be used in
the [Function](#spec-function) within the contract, it is equivalent to the
global variable of the contract. You can use it directly or reassign it.
```go
contract Name {
data {
Param1 string "optional"
}
func name(){
$Param1 = 4
Println($Param1)
}
}
```
### Settings {#spec-settings}
Use the `settings` keyword to declare constants, the type of constant value can
be `int`, `float`, `string`, `bool`, it must be within the `contract`.
constants value only can be assigned once, and cannot be changed during the
execution of the contract.
> `SettingsStmt` = `"settings"` `SettingsScope` .
>
> `SettingsScope` = `"{"` [Identifier](#spec-identifier) `"="` (
> [Number Literal](#spec-number) | [String Literal](#spec-string) |
> [Boolean Literal](#spec-boolean) ) `"}"` .
```go
contract Name {
settings {
i = 1
f = 1.2
b = true
s = "this is a string"
}
}
```
### Function {#spec-function}
This function processes the [Data](#spec-data) and [Settings](#spec-settings) in
the smart contract. It performs operations such as arithmetic, type conversion,
and establishing interactions between contracts.
#### Function Declaration {#function-decl}
Functions are declared with the `func` keyword followed by the function name,
parameters, type parameters, function tail, a return type and finally the
function body.
> `FuncDecl` = "func" FuncName `FuncSign` `FuncBody` .
>
> `FuncName` = [Identifier](#spec-identifier) .
>
> `FuncBody` = [CodeBlockStmt](#spec-codeblock) .
>
> `FuncSign` = [ `FuncParams` ] [ `FuncTail` ] [ `FuncResult` ] .
>
> `FuncParams` = `"("` [ `FuncParamList` ] `")"` .
>
> `FuncParamList` = `FuncParam` `{` `FuncParamSeq` `}` [ ( `","` | `" "` )
> [IdentifierList](#spec-identifier) `"..."` ] .
>
> `FuncParam` = [IdentifierList](#spec-identifier) [Typename](#spec-typename) .
>
> `FuncParamSeq` = ( `","` | `" "` ) `FuncParam` .
>
> `FuncResult` = [TypeList](#spec-typename) .
>
> `FuncTail` = `"."` [Identifier](#spec-identifier) [ `FuncParams` ] .
The function can have multiple parameters, each parameter followed by a
parameter name and type, separated by a space or comma. The return value cannot
be enclosed in parentheses `()`, and the return type cannot declare its variable
name. Use the keyword `return` to return one or more values.
```go
func Add(a b, c int, s string) int string{
if a {
return a + b + c, s
}
// invalid: missing return statement.
}
```
If the function does not declare a parameter list, the parentheses `()` in the
function signature can be omitted, and in this case, the type declaration after
the function name is called the result parameter.
```go
func Get string{
return "string"
}
```
The function signature can use `...` to represent the type of variadic
parameters, which must be the last parameter, and its data type is
[array](#spec-typename). The variadic parameter contains all the variables
starting from the call to pass the parameter. Any type of variable can be
passed, but conflicts with data types need to be handled.
```go
func sum(out string, values ...) {
//...
}
func Name() {
sum("Sum:", 10, "20", 30.3)
}
```
THe function thought the `return` statement returns a value, it will not be
passed to other contracts. If you want to pass the return value of the contract
to another contract, you need to assign the return value to the `$result`
variable.
```go
contract NameB {
action {
$result = 11
}
}
contract NameA {
action {
var a int
a = NameB()
}
}
```
If the function name is `action` or `conditions`, the `func` can be omitted.
```go
contract Name {
action {}
conditions {}
}
```
#### Tail function {#tail-function}
The function may have many parameters, but when calling them, you only want to
pass some of them. In this case, you can declare multiple functions with a dot,
such functions are called `tail functions`, and then you can call the specified
parameters in any order, without having to call them in the order declared. In
such a function body, you can use these parameters normally. If no parameters
are passed, they will be assigned default values. Tail functions do not have
return values, and the return values are part of the main function.
```go
func myfunc(name string).Param1(p1 int).Param2(p2 string) int {
//...
}
func Name{
myfunc("name").Param2("p2")
}
```
Different functions can be called using a dot. When calling a function, the
return value of this function can be used as the input of the next function, and
the return value is obtained in the order of definition. Multiple tail functions
are only visible to the main function, not to other functions. Tail functions
cannot be called separately, they must be connected to the main function or
other tail functions under the main function.
```go
func A(int).tailA() int, string
func B(string,bool) string
func Name(){
B("B",true).A(2)
A(2).B(true).tailA()//invalid
tailA() //invalid
}
```
## Syntax base {#syntax-base}
The source code must be encoded using UTF-8.
### Code block {#spec-codeblock}
The curly braces `{}` specify a code block that can contain local variables.
Variables in the code block can only be used in the code block and its sub-code
block. The function body is also a code block.
> `CodeBlockStmt` = `"{"` ... `"}"` .
By default, variables in a code block are not visible, and the scope of a
variable can be extended to its sub-code block. In a code block, you can use the
name of an existing variable to define a new variable. Therefore, it is not
visible outside its scope. When the scope ends, the variable will be destroyed.
```go
contract Name {
func block {
var a int
a = 3
if ture {
var a int
a = 4
}
}
}
```
### Comment {#spec-comment}
Comments can be used as documentation, and the content of the comments will be
ignored by the compiler. There are two types of comments, one is **single-line
comments**, and the other is **multi-line comments**.
1. Single line comments start with `//` and end at the end of the line.
```go
func add(a int, b int) int {
// This is a comment
return a + b // This is also a comment
}
```
2. Multi-line comments start with `/*` and end with `*/`. Multi-line comments
are not affected by newline characters, can span multiple lines, and can be
commented out anywhere.
```go
func /*here*/a() {
var b /*there*/ int
/*
here
*/
b = /*there*/ 2
}
/*everywhere*/
```
### Newline {#spec-newline}
The newline character is a delimiter between expressions and statements, and the
newline character is replaced by a semicolon `;`, which can be used to separate
multiple expressions or statements.
```go
var a int
a = 1
//can be written as
var a int; as = 1
```
### Delimiter {#spec-delimiter}
Delimiter are used to separate identifiers, such as variable names, function
names, type names, etc.
> `Delimiter` = `"("` | `")"` | `"{"` | `"}"` | `"["` | `"]"` | `"."` | `"," `|
> `"="` | `":"` .
### Expression {#spec-expression}
Expression refers to a statement that calculates a value. An expression consists
of constants, variables, operators, and functions. A definite value can be
obtained after calculation. The expression does not change the value, it just
calculates a value.
Some examples of expressions, not limited to:
- Literals, including string literals, numeric literals, such as: `100`, `3.14`,
`"hello"`.
- Variable names, such as: `x`, `sum`.
- Arithmetic expressions, such as: `1 + 2`, `a * b`.
- Function call expressions, such as: `fnName()`.
- Comparison expressions, such as: `a == b`, `score > 90`.
- Logical expressions, such as: `a && b`, `!done`.
- Array, slice, map index expression, such as: `array[2]`, `map["key"]`,
`slice[1:3]`.
- Type conversion expression, such as: `Int(a)`.
The value obtained by calculating the expression can be assigned to a variable,
used as a parameter to a function, combined with other expressions to form more
complex expressions, and used in if condition statements to control the program
flow.
### Identifier {#spec-identifier}
Identifiers are used to identify variables, functions, constants, and other
program names. Identifiers are composed of one or more letters `A|a` to `Z|z`,
numbers `0` to `9`, and underscores `_`, and must begin with a letter.
Identifiers cannot contain spaces and special characters. Identifiers are
case-sensitive and cannot use [keywords](#spec-keyword) as identifiers.
> `Identifier` = `unicode_letter` `{` `letter` | `unicode_digit` `}`
>
> `letter` = `unicode_letter` | `"_"` .
>
> `unicode_letter` = // a Unicode code point classified as "Letter".
>
> `unicode_digit` = // a Unicode code point categorized as "Number, decimal
> digit".
>
> `IdentifierList` = `Identifier` `{` `IdentifierSeq` `}` .
>
> `IdentifierSeq` = ( `","` | `" "` ) `Identifier`
```go
a
x_123
αβ
```
Multiple identifiers can be combined into an identifier list, separated by
commas or spaces.
### Keyword {#spec-keyword}
The following keywords are reserved and cannot be used as
[identifiers](#spec-identifier).
| | | | | |
| -------- | ----- | ----- | -------- | ---------- |
| contract | func | data | action | conditions |
| return | if | elif | else | while |
| var | nil | break | continue | settings |
| true | false | info | warning | error |
| ... | | | | |
### Number {#spec-number}
Number literal values include: `decimal` integer, `binary` integer, `octal`
integer, `hexadecimal` integer, and floating-point number and scientific
notation.
There are two basic types: `int` and `float`. If the number contains a decimal
point or `eE`, it is a **float** type, which conforms to the standard IEEE-754
64-bit floating-point number, otherwise it is an **int** type. int is equivalent
to int64 in the Golang language, and float is equivalent to float64 in the
Golang language.
> `int` = `DecimalLit` | `BinaryLit` | `OctalLit` | `HexLit` .
>
> `float` = `FloatLit` .
>
> `decimal_digit` = "0"..."9" .
>
> `binary_digit` = "01" .
>
> `octal_digit` = "0"..."7" .
>
> `hex_digit` = "0"..."9" | "A"..."F" | "a"..."f" .
>
> `binary_digits` = `binary_digit` `{` [ "_" ] `binary_digit`.`}` .
>
> `decimal_digits`= `decimal_digit` `{` [ "_" ] `decimal_digit`. `}` .
>
> `octal_digits` = `octal_digit` `{` [ "_" ] `octal_digit` `}` .
>
> `hex_digits` = `hex_digit` `{` [ "_" ] `hex_digit` `}` .
>
> `DecimalLit` = `decimal_digit` [ "_" ] `decimal_digits` .
>
> `BinaryLit` = "0" ( "b" | "B" ) [ "_" ] `binary_digits` .
>
> `OctalLit` = "0" ( "o" | "O" ) [ "_" ] `octal_digits` .
>
> `HexLit` = "0" ( "x" | "X" ) [ "_" ] `hex_digits` .
>
> `ExponentPart` = ( "e" | "E" ) [ "+" | "-" ] `decimal_digits` .
>
> `FloatLit` = `decimal_digits` "." [ `decimal_digits` ] [ `ExponentPart` ] |
> `decimal_digits` `ExponentPart` | "." `decimal_digits` [ `ExponentPart` ] .
```
0
123
0b101
0o123
0xaf
0.123
1.23e+2
.3e+2
```
### String {#spec-string}
String literals can be enclosed in double quotes `"` or backticks `` ` ``, and
string literals enclosed in backticks can span multiple lines. The string in
double quotes can contain escape sequences for double quotes, newline, and
carriage return. The string in backticks is not escaped.
> `StringLiteral` = `RawStringLiteral` | `InterpretedStringLiteral` .
>
> `RawStringLiteral` = ``"`"`` { `unicode_char` } ``"`"`` .
>
> `InterpretedStringLiteral` = `"` { `unicode_value` } `"` .
>
> `unicode_char` = // an arbitrary Unicode code point except newline.
>
> `unicode_value` = // an arbitrary Unicode code point.
```go
var str string
str = "This is \n a string"
str = `This is \n \t \r a other string`
```
### Boolean {#spec-boolean}
A boolean type has two values: `true` and `false`. It is used to represent the
truth value of an expression.
> `Boolean` = "true" | "false" .
### Variable {#spec-variable}
Variables are used to store values, and the values allowed by variables are
determined by their types. The type is immutable, but the value can be changed
during program execution.
#### Local Variable {#local-variable}
The keyword `var` is used to declare local variables, and the variable must be
followed by a variable name and type.
> `LocalVarDecl` = `"var"` [IdentifierList](#spec-identifier) >
> [Typename](#spec-typename) .
When declaring a variable, its value is the default value. To declare one or
more variables, you can use a comma or space to separate multiple variable names
and types. When the types of two or more consecutive named formal parameters of
a function are the same, all types except the last one can be omitted.
```go
var a int
var b b1, b2 string
var c bool, c1 float
b = "string"
b1, b2 = "string1", "string2"
c c1 = true 1.2
```
Variables cannot be initialized when declared, and must be assigned after
declaration.
```go
// invalid
var a int = 1
// good
var a int
a = 1
```
The types `map` and `array` do not support multiple assignments on the same line
using `{}` and `[]`, but multiple assignments on the same line can be done using
variable names.
```go
var a b int c c1 map d d1 array
a, b = 1, 2
c,d = {"a":a, "b":b}, [1, 2, 3] //invalid
c = {"a":a, "b":b}
d = [1, 2, 3]
c1, d1 = c, d
d[0], d[1] = c, d //invalid
d[0], d[1] = d[1], d[0] //invalid
```
#### Global Variable {#global-variable}
The keyword symbol `$` and [Identifier](#spec-identifier) is used to declare and
use global variables. The syntax is as follows:
> `GlobalVarDecl` = `"$"` [Identifier](#spec-identifier) .
Global variables can be declared in any function within a single contract scope,
but must be declared before use. The parameters defined in the `data` section
are also global variables, but can only be used within the current contract
scope.
```go
contract Name {
data {
param int
}
func set() {
$abc = 1
}
func get() int {
$abc = $abc + $param
return $abc
}
}
```
#### Predeclared global variables {#predeclared-global-variables}
Predeclared global variables can be used in any contract scope and these global
variables can be specified as immutable during compilation, which is mutable by
default.
Predeclared global variables include:
- `$original_contract` - name of the contract that initially processed the
transaction. It means the contract is called during transaction validation if
the variable is an empty string. To check whether the contract is called by
another contract or directly by the transaction, you need to compare the
values of $original_contract and $this_contract. It means that the contract is
called by the transaction if they are equal.
- `$this_contract` - name of the contract currently being executed.
- `$stack` - contract array stack with a data type of [array](#spec-typename),
containing all contracts executed. The first element of the array represents
the name of the contract currently being executed, while the last element
represents the name of the contract that initially processed the transaction.
- `$result` - assigned with the return result of the contract.
### Typename {#spec-typename}
All variables have types, and type names are used to represent the data types of
variables.
> `Type` = `Typename` | `TypeList` .
>
> `Typename` = "int" | "string" | "float" | "bool" | "bytes" | "address" |
> "money" | "array" | "map" | "file" .
>
> `TypeList` = `Typename` `{` ( "," | " " ) `Typename` `}` .
The following type names are reserved and cannot be used as identifiers,
equivalent to the corresponding types in the Golang language.
- **int** - `int64`, zero value is `0`.
- **string** - `string`, zero value is `""`.
- **float** - `float64`, zero value is `0.0`.
- **bool** - `bool`, zero value is `false`.
- **bytes** - `[]byte`, zero value is `[]byte`.
- **array** - `[]interface{}`, zero value is `[]`.
- **map** - `map[string]interface{}`, zero value is `map[]`.
- **address** - `int64`, zero value is `0`.
- **money** - [decimal.Decimal](https://github.com/shopspring/decimal), zero
value is `0`.
- **file** - `map[string]interface{}`, zero value is `map[]`.
#### Object and array literals {#object-and-array-literals}
`array` and `map` types can be created using `[]` and `{}` operators or
specified elements.
`array` type index must be `int`. `map` type index must be `string`. If a value
is assigned to an index greater than the current maximum index of the `array`
element, an empty element will be added to the array. The initialization value
of these elements is `nil`.
```go
var arr array m map
arr = [1,2,3]
arr[0] = 4
m = {"key": "value"}
m = {"key": myfunc()} // invalid
m = {"key": arr[0]} // invalid
m["key1"] = arr[5] // m["key1"] = nil
```
### Operator {#spec-operator}
An operation expression consists of an operator and an operand. Needle supports
the following operation operators: arithmetic operators, comparison operators,
logical operators, bitwise operators, and assignment operators.
Follow are the currently supported operators:
- arithmetic operators: `+`, `-`, `*`, `/`, `%`, `++`, `--`.
- comparison operators: `==`, `!=`, `>`, `>=`, `<`, `<=`.
- logical operators: `&&`, `||`, `!`.
- bitwise operators: `&`, `|`, `^`, `<<`, `>>`.
- assignment operators: `=`, `+=`, `-=`, `*=`, `/=`, `%=`, `&=`, `|=`, `^=`,
`<<=`, `>>=`.
The priority of the operators is from high to low:
- `++`, `--`, `!`.
- `*`, `/`, `%`.
- `+`, `-`.
- `<<`, `>>`.
- `<`, `<=`, `>`, `>=`.
- `==`, `!=`.
- `&`.
- `^`.
- `|`.
- `&&`.
- `||`.
- `=`, `+=`, `-=`, `*=`, `/=`, `%=`, `&=`, `|=`, `^=`, `<<=`, `>>=`.
The result type of the operation is the same as the type of the operand. Except
for comparison operators and logical operators, their result type is `bool`. In
logical expressions, the result type will be automatically converted to a
logical value, if the operand type is not the default value, and the result is
`true`.
`a += b` is equivalent to `a = a + b`, `-=`, `*=`, `/=`, `%=`, `&=`, `|=`, `^=`,
`<<=`, `>>=` are also defined in this way. `a++` is equivalent to `a += 1`.
Even if the types of the two operands are different, Needle allows the use of
operators in expressions. In this case, the operands will be converted to the
same type and then the operation will be performed. For example, to calculate
`z = x + y`, where `x` is of type `int` and `y` is of type `float`, `x` and `y`
will both be converted to type `decimal`. Then the addition operation is
performed, and the result is of type `decimal`, which is then converted to type
`float` and assigned to `z`.
It should be noted that when performing floating-point operations, the issue of
precision loss should be considered to avoid incorrect results.
The following lists the operators and result types between operands of different
types:
| operand | x | y | z | |
| ----------------------------- | ------- | ------- | ------- | -------------------------- |
| not(`!`) | - | | bool | y to bool |
| unary(`+`,`-`) | - | int | int | |
| | - | float | float | |
| `<<` , `>>` | int | int | int | |
| `&`,`^`,`｜` | int | int | int | |
| `++` , `--` | int | int | int | |
| `+`,`-`,`*`,`/`,`%` | string | string | string | (only `+`) |
| | string | int | int | x to int |
| | string | float | float | x to decimal, y to decimal |
| | float | string | float | x to decimal, y to decimal |
| | float | int | float | x to decimal, y to decimal |
| | float | float | float | x to decimal, y to decimal |
| | int | string | int | y to int |
| | int | int | int | |
| | int | float | float | x to decimal, y to decimal |
| | decimal | string | decimal | y to decimal |
| | decimal | int | decimal | y to decimal |
| | decimal | float | decimal | y to decimal |
| | decimal | decimal | decimal | |
| `&&`,`\|\|` | | | bool | x to bool, y to bool |
| `==` ,`!=` ,`<`,`<=`,`>`,`>=` | nil | nil | bool | only(`==` ,`!=`) |
| | bool | bool | bool | only(`==` ,`!=`) |
| | string | string | bool | |
| | string | int | bool | y to string |
| | string | float | bool | y to string |
| | string | decimal | bool | y to string |
| | float | string | bool | x to decimal, y to decimal |
| | float | int | bool | x to decimal, y to decimal |
| | float | float | bool | x to decimal, y to decimal |
| | float | decimal | bool | x to decimal |
| | int | string | bool | y to int |
| | int | int | bool | |
| | int | float | bool | x to decimal, y to decimal |
| | int | decimal | bool | y to int |
| | decimal | string | bool | y to decimal |
| | decimal | int | bool | y to decimal |
| | decimal | float | bool | y to decimal |
| | decimal | decimal | bool | |
| | | | | |
### Slice {#spec-slice}
The slice operation only applies to the types `array`, `string`, and `bytes`.
The slice operator `[low:high]` is used to get a part of the array.
```go
arr[low:high]
```
The range of the index must be positive. If `0<=low<=high<=len(arr)`, the index
range is valid, otherwise the index range is invalid. For convenience, any index
can be omitted. The omitted index will be replaced by the first index or the
last index of the array.
```go
var a b c d e array str strA string
a = [1,2,3,4,5]
b = a[1:3] // b = [2,3]
c = a[1:] // c = [2,3,4,5]
d = a[:3] // d = [1,2,3]
e = a[:] // e = [1,2,3,4,5]
str = "abcd"
strA = str[1:3] // strA = "bc"
```
### Increment and Decrement {#spec-increment-and-decrement}
`++` and `--` increment and decrement the variables of type `int`, `float`, and
`money`, which can increase or decrease the variable value by 1.
```go
var i int f float m money
i++
f--
m++
```
### Control Statement {#spec-control-statement}
Control statements are used to control the execution flow of the program,
including return statements, if statements, while statements, break statements,
and continue statements.
> `ControlStmt` = [ReturnStmt](#return-statement) | [IfStmt](#if-statement) |
> [WhileStmt](#while-statement) | [BreakStmt](#break-statement) |
> [ContinueStmt](#continue-statement) .
In if statements, the conversion from non-boolean types to boolean types is
supported. The following rules convert boolean types to `false`, otherwise
`true`. So, code like `if 1 {}` is valid.
- `int` and `float`, `money`, `string`, `address` type values are equal to the
zero value.
- `array` and `map`, `bytes`, `file` type values are equal to nil or their
length is zero.
#### Return statement {#return-statement}
The `return` statement is used in the function body to terminate the execution
of the function prematurely. If the function declares result parameters, the
`return` statement must return the same type and number of values.
> `ReturnStmt` = "return" [ExpressionList](#spec-expression) .
```go
func add(a , b int) int {
return a + b
}
```
#### If statement {#if-statement}
`if` statement executes the code block based on the value of the boolean
expression. If the expression evaluates to `true`, the `if` code block is
executed, otherwise the `else` code block is executed.
`elif` is actually equivalent to `else if`, it must be defined before the `else`
statement.
> `IfStmt` = "if" [Expression](#spec-expression) >
> [CodeBlockStmt](#spec-codeblock) { `ElIfStmtList` } [`ElseStmt`] .
>
> `ElIfStmtList` = "elif" [Expression](#spec-expression) >
> [CodeBlockStmt](#spec-codeblock) .
>
> `ElseStmt` = "else" [CodeBlockStmt](#spec-codeblock) .
```go
if a > b {
Println("a is greater than b")
} elif a == b {
Println("a and b are equal")
} else {
Println("b is greater than a")
}
```
#### while statement {#while-statement}
The `while` statement provides the ability to repeatedly execute a code block as
long as the expression evaluates to `true`. The condition is evaluated before
each iteration.
> `WhileStmt` = "while" [Expression](#spec-expression) >
> [CodeBlockStmt](#spec-codeblock) .
```c
var a int
while a < 10 {
a++
}
```
:::tip
If the condition is always `true`, the `while` statement will be executed
repeatedly. Therefore, it should include a condition that is `false` at some
point.
:::
#### Break statement {#break-statement}
The `break` statement terminates the innermost `while` statement.
> `BreakStmt` = "break" .
```go
var a int
a = 1
while a < 10 {
if a == 5 {
break
}
a++
}
```
#### Continue statement {#continue-statement}
`continue` statement skips the remaining code of the innermost `while` statement
and continues with the next iteration of the loop.
> `ContinueStmt` = "continue" .
```go
var a int
a = 1
while a < 10 {
if a == 5 {
continue
}
a++
}
```
---
## File: docs/howtos/deployment.md
# Deployment of A IBAX Network
In this section, we will show you how to deploy your own blockchain network.
## An deployment example {#an-deployment-example}
A blockchain network will be deployed with the following three nodes as an
example.
Three network nodes:
- Node 1 is the first node in the blockchain network, which can generate new
blocks and send transactions from clients connected to it;
- Node 2 is another honor node, which can generate new blocks and send
transactions from clients connected to it;
- Node 3 is a guardian node, which cannot generate new blocks, but can send
transactions from clients connected to it.
Configurations of the three nodes to be deployed:
- Each node uses its own PostgreSQL database system instance;
- Each node uses its own Centrifugo service instance;
- The server side github-backend is deployed on the same host as other backend
components.
The sample addresses and ports used by the nodes are described in the following
table:
| Node | Component | IP & port |
| :--: | :-------------------: | :--------------: |
| 1 | PostgreSQL | 127.0.0.1:5432 |
| 1 | Centrifugo | 192.168.1.1:8000 |
| 1 | go-ibax (TCP service) | 192.168.1.1:7078 |
| 1 | go-ibax (API service) | 192.168.1.1:7079 |
| 2 | PostgreSQL | 127.0.0.1:5432 |
| 2 | Centrifugo | 192.168.1.2:8000 |
| 2 | go-ibax (TCP service) | 192.168.1.2:7078 |
| 2 | go-ibax (API service) | 192.168.1.2:7079 |
| 3 | PostgreSQL | 127.0.0.1:5432 |
| 3 | Centrifugo | 192.168.1.3:8000 |
| 3 | go-ibax (TCP service) | 192.168.1.3:7078 |
| 3 | go-ibax (API service) | 192.168.1.3:7079 |
## Deploy phase {#deploy-phase}
Your own blockchain network must be deployed in several stages:
- [An deployment example](#an-deployment-example)
- [Deploy phase](#deploy-phase)
- [Server deployment](#server-deployment)
- [Deploy the first node](#deploy-the-first-node)
- [Dependencies and environment settings](#dependencies-and-environment-settings)
- [sudo](#sudo)
- [Golang](#golang)
- [PostgreSQL](#postgresql)
- [Centrifugo](#centrifugo)
- [Directory structure](#directory-structure)
- [Create a database](#create-a-database)
- [Configure Centrifugo](#configure-centrifugo)
- [Install go-ibax](#install-go-ibax)
- [Configure the first node](#configure-the-first-node)
- [Initiate the first node server](#initiate-the-first-node-server)
- [Deploy other nodes](#deploy-other-nodes)
- [Node 2](#node-2)
- [Node 3](#node-3)
- [Front-end deployment](#front-end-deployment)
- [Software prerequisites](#software-prerequisites)
- [Build a Weaver application](#build-a-weaver-application)
- [Add the configuration file for the blockchain network](#add-the-configuration-file-for-the-blockchain-network)
- [Build Weaver Web Application](#build-weaver-web-application)
- [Configure the blockchain network](#configure-the-blockchain-network)
- [Create the creator account](#create-the-creator-account)
- [Import applications, roles and templates](#import-applications-roles-and-templates)
- [Add the first node to the node list](#add-the-first-node-to-the-node-list)
- [Add other honor nodes](#add-other-honor-nodes)
- [Add members into the consensus role group](#add-members-into-the-consensus-role-group)
- [Create the owner account for other nodes](#create-the-owner-account-for-other-nodes)
- [Assign the node owner with the Validators role](#assign-the-node-owner-with-the-validators-role)
## Server deployment {#server-deployment}
### Deploy the first node {#deploy-the-first-node}
The first node is a special one because it is essential to launch the blockchain
network. The first block of the blockchain is generated by the first node, and
all other nodes would download the blockchain from it. The owner of the first
node is the platform creator.
### Dependencies and environment settings {#dependencies-and-environment-settings}
#### sudo {#sudo}
All commands of Debian 9 must be run as a non-root user. However, some system
commands require super user permissions to execute. By default, sudo is not
installed on Debian 9, you must install it first.
1. Become a super user.
```shell
su -
```
2. Upgrade your system.
```shell
apt update -y && apt upgrade -y && apt dist-upgrade -y
```
3. Install sudo.
```shell
apt install sudo -y
```
4. Add your user to the sudo group.
```shell
usermod -a -G sudo user
```
5. After restarting, the changes take effect.
### Golang {#golang}
Install Go according to the
[Official Documents](https://golang.org/doc/install#tarball).
1. Download the latest stable version of Go (> 1.10.x) from
[Golang official website](https://golang.org/dl/) or through the command
line:
```shell
wget https://dl.google.com/go/go1.11.2.linux-amd64.tar.gz
```
2. Use tar to extract the tarball to the `/usr/local` directory.
```shell
tar -C /usr/local -xzf go1.11.2.linux-amd64.tar.gz
```
3. Add `/usr/local/go/bin` to PATH environment variables (located at
`/etc/profile` or `$HOME/.profile`).
```shell
export PATH=$PATH:/usr/local/go/bin
```
1. Execute the `source` file to make the changes take effect, for example:
```shell
source $HOME/.profile
```
2. Delete temporary files:
```shell
rm go1.11.2.linux-amd64.tar.gz
```
### PostgreSQL {#postgresql}
1. Install PostgreSQL (> v.10) and psql:
```shell
sudo apt install -y postgresql
```
### Centrifugo {#centrifugo}
1. Download Centrifugo V.1.8.0 from
[GitHub](https://github.com/centrifugal/centrifugo/releases/) or through the
command line:
```shell
wget https://github.com/centrifugal/centrifugo/releases/download/v1.8.0/centrifugo-1.8.0-linux-amd64.zip \
&& unzip centrifugo-1.8.0-linux-amd64.zip \
&& mkdir centrifugo \
&& mv centrifugo-1.8.0-linux-amd64/* centrifugo/
```
2. Delete temporary files:
```shell
rm -R centrifugo-1.8.0-linux-amd64 \
&& rm centrifugo-1.8.0-linux-amd64.zip
```
### Directory structure {#directory-structure}
For the Debian 9 system, it is recommended to store all software used by the
blockchain platform in a separate directory.
The `/opt/backenddir` directory is used here, but you can use any directory. In
this case, please change all commands and configuration files accordingly.
1. Create a directory for the blockchain platform:
```shell
sudo mkdir /opt/backenddir
```
2. Make your user the owner of the directory:
```shell
sudo chown user /opt/backenddir/
```
3. Create subdirectories for Centrifugo, go-ibax and node data. All node data is
stored in a directory named `nodeX`, where `X` is the node number. According
to the node to be deployed, `node1` is Node 1, `node2` is Node 2, and so
forth.
```shell
mkdir /opt/backenddir/go-ibax \
mkdir /opt/backenddir/go-ibax/node1 \
mkdir /opt/backenddir/centrifugo \
```
### Create a database {#create-a-database}
1. Change the user password postgres to the default password _123456_. You can
set your own password, but you must change it in the node configuration file
_config.toml_.
```shell
sudo -u postgres psql -c "ALTER USER postgres WITH PASSWORD '123456'"
```
2. Create a current state database for the node, for example **chaindb**:
```shell
sudo -u postgres psql -c "CREATE DATABASE chaindb"
```
### Configure Centrifugo {#configure-centrifugo}
1. Create the Centrifugo configuration file:
```shell
echo '{"secret":"CENT_SECRET"}' > /opt/backenddir/centrifugo/config.json
```
You can set your own _secret_, but you must also change it in the node
configuration file _config.toml_.
### Install go-ibax {#install-go-ibax}
1. Download github-backend from GitHub:
2. Copy the go-ibax binary file to the `/opt/backenddir/go-ibax` directory. If
you are using default Go workspace, the binary files are located in the
`$HOME/go/bin` directory:
```shell
cp $HOME/go/bin/go-ibax /opt/backenddir/go-ibax
```
### Configure the first node {#configure-the-first-node}
3. Create the configuration file for Node 1:
```shell
/opt/backenddir/go-ibax config \
--dataDir=/opt/backenddir/node1 \
--dbName=chaindb \
--centSecret="CENT_SECRET" --centUrl=http://192.168.1.1:8000 \
--httpHost=192.168.1.1 \
--httpPort=7079 \
--tcpHost=192.168.1.1 \
--tcpPort=7078
```
4. Generate the keys of Node 1, including the public and private keys of the
node and the account:
```shell
/opt/backenddir/go-ibax generateKeys \
--config=/opt/backenddir/node1/config.toml
```
5. Generate the first block:
:::tip
If you want to create your own blockchain network, you must use the
`--test=true` option. Otherwise, you cannot create a new account.
:::
```shell
/opt/backenddir/go-ibax generateFirstBlock \
--config=/opt/backenddir/node1/config.toml \
--test=true
```
6. Initialize the database:
```shell
/opt/backenddir/go-ibax initDatabase \
--config=/opt/backenddir/node1/config.toml
```
### Initiate the first node server {#initiate-the-first-node-server}
To start the first node server, you must start the following two services:
- centrifugo
- go-ibax
If you failed to create [services](https://wiki.debian.org/systemd/Services)
with these files, you may execute binary files from directories in different
consoles.
1. Run centrifugo:
```shell
/opt/backenddir/centrifugo/centrifugo \
-a 192.168.1.1 -p 8000 \
--config /opt/backenddir/centrifugo/config.json
```
2. Run go-ibax:
```shell
/opt/backenddir/go-ibax start \
--config=/opt/backenddir/node1/config.toml
```
## Deploy other nodes {#deploy-other-nodes}
Although the deployment of all other nodes (Node 2 and Node 3) is similar to the
first, but there are three differences:
- You do not need to generate the first block. But it must be copied from Node 1
to the current node data directory;
- The node must download blocks from Node 1 by configuring the `--nodesAddr`
option;
- The node must use its own addresses and ports.
### Node 2 {#node-2}
Follow operational instructions as shown below:
1. [Dependencies and environment settings](#dependencies-and-environment-settings)
2. [Create database](#create-a-database)
3. [Centrifugo](#centrifugo)
4. [Install go-ibax](#install-go-ibax)
5. Create the configuration file for Node 2:
```shell
/opt/backenddir/go-ibax config \
--dataDir=/opt/backenddir/node2 \
--dbName=chaindb \
--centSecret="CENT_SECRET" --centUrl=http://192.168.1.2:8000 \
--httpHost=192.168.1.2 \
--httpPort=7079 \
--tcpHost=192.168.1.2 \
--tcpPort=7078 \
--nodesAddr=192.168.1.1
```
6. Copy the first block file to Node 2. For example, you can perform this
operation on Node 2 throughscp:
```shell
scp user@192.168.1.1:/opt/backenddir/node1/1block /opt/backenddir/node2/
```
7. Generate the keys of Node 2, including the public and private keys of the
node and the account:
```shell
/opt/backenddir/go-ibax generateKeys \
--config=/opt/backenddir/node2/config.toml
```
8. Initiate the database:
```shell
./go-ibax initDatabase --config\=node2/config.toml
```
9. Run centrifugo:
```shell
/opt/backenddir/centrifugo/centrifugo \
-a 192.168.1.2 -p 8000 \
--config/opt/backenddir/centrifugo/config.json
```
10. Run go-ibax:
```shell
/opt/backenddir/go-ibax start \
--config=/opt/backenddir/node2/config.toml
```
As a result, the node downloads the block from the first node. As this node is
not a verification node, it cannot generate a new block. Node 2 will be added to
the list of verification nodes later.
### Node 3 {#node-3}
Follow operational instructions as shown below:
1. [Dependencies and environment settings](#dependencies-and-environment-settings)
2. [Create database](#create-a-database)
3. [Centrifugo](#centrifugo)
4. [Install go-ibax](#install-go-ibax)
5. Create the configuration file for Node 3:
```shell
/opt/backenddir/go-ibax config \
--dataDir=/opt/backenddir/node3 \
--dbName=chaindb \
--centSecret="CENT_SECRET" --centUrl=http://192.168.1.3:8000 \
--httpHost=192.168.1.3 \
--httpPort=7079 \
--tcpHost=192.168.1.3 \
--tcpPort=7078 \
--nodesAddr=192.168.1.1
```
6. Copy the first block file to Node 3. For example, you can perform this
operation on Node 3 through scp:
```shell
scp user@192.168.1.1:/opt/backenddir/node1/1block /opt/backenddir/node3/
```
7. Generate the key of Node 3, including the public and private keys of the node
and the account:
```shell
/opt/backenddir/go-ibax generateKeys \
--config=/opt/backenddir/node3/config.toml
```
8. Initiate the database:
```shell
./go-ibax initDatabase --config=node3/config.toml
```
9. Run centrifugo:
```shell
/opt/backenddir/centrifugo/centrifugo \
-a 192.168.1.3 -p 8000 \
--config/opt/backenddir/centrifugo/config.json
```
10. Run go-ibax:
```shell
/opt/backenddir/go-ibax start \
--config=/opt/backenddir/node3/config.toml
```
As a result, the node downloads the block from the first node. As this node is
not a verification node, it cannot generate a new block. The client may be
connected to the node, and it may send transactions to the network.
## Front-end deployment {#front-end-deployment}
Only after installing **GNOME GUI** on Debian 9 (Stretch) 64-bit Official
Release, the Govis client can be built with the `yarn` package manager.
### Software prerequisites {#software-prerequisites}
1. Download Node.js LTS version 8.11 from Node.js official website or through
the command line:
```shell
curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash
```
2. Install Node.js:
```shell
sudo apt install -y nodejs
```
a) Download Yarn version 1.7.0 from yarn's
[Github](https://github.com/yarnpkg/yarn/releases) repository or through the
command line:
```shell
cd/opt/backenddir \
&& wget https://github.com/yarnpkg/yarn/releases/download/v1.7.0/yarn_1.7.0_all.deb
```
b) Install Yarn:
```shell
sudo dpkg -i yarn_1.7.0_all.deb && rm yarn_1.7.0_all.deb
```
### Build a Weaver application {#build-a-weaver-application}
1. Download the latest version of Weaver from github-frontend via git:
```shell
cd/opt/backenddir \
&& git clone https://github.com/ibax-io/ibax-front.git
```
2. Install Weaver dependencies via Yarn:
```shell
cd/opt/backenddir/ibax-front/ \
&& yarn install
```
### Add the configuration file for the blockchain network {#add-the-configuration-file-for-the-blockchain-network}
1. Create a _settings.json_ file that contains information about node
connection:
```shell
cp/opt/backenddir/ibax-front/public/settings.json.dist \
/opt/backenddir/ibax-front/public/public/settings.json
```
2. Edit the _settings.json_ file in any text editor and add the required
settings in this format:
```
http://Node_IP-address:Node_HTTP-Port
```
Examples of _settings.json_ files for the three nodes:
```json
{
"fullNodes": [
"http://192.168.1.1:7079",
"http://192.168.1.2:7079",
"http://192.168.1.3:7079"
]
}
```
Build Weaver Desktop Application:
1. Use yarn to build the desktop version:
```shell
cd/opt/backenddir/ibax-front \
&& yarn build-desktop
```
2. The desktop version will be packaged into AppImage suffix format:
```shell
yarn release --publish never -l
```
After building, your application can be used, but its connection configuration
cannot be changed. If these settings need to be changed, a new version of the
application must be built.
### Build Weaver Web Application {#build-weaver-web-application}
1. Build a web application:
```shell
cd/opt/backenddir/ibax-front/ \
&& yarn build
```
After building, the redistributable files will be placed in the /build
directory. You can use any web server of your choice for deployment, and the
_settings.json_ file must also be placed in this directory. Note that if the
connection settings are changed, there is no need to build the application
again. Instead, edit the _settings.json_ file and restart the web server.
1. For development or testing purposes, you can build Yarn's web server:
```shell
sudo yarn global add serve \
&& serve -s build
```
After that, your Weaver web application will be available at the following
location: `http://localhost:5000`.
## Configure the blockchain network {#configure-the-blockchain-network}
### Create the creator account {#create-the-creator-account}
Create an account for the first node owner. This account is the creator of the
new blockchain platform and has the administrator access.
1. Run Weaver;
2. Import the existing account using the following data:
–Load the backup of the node owner's private key located in the
`/opt/backenddir/node1/PrivateKey` file.
:::tip
There are two private key files in this directory. The `PrivateKey` file is used
create the node owner's account. The `NodePrivateKey` file is the private key of
the node itself and must be kept secret.
:::
3. After logging in to the account, since no role has been created at this time,
please select the Without role option.
### Import applications, roles and templates {#import-applications-roles-and-templates}
At this time, the blockchain platform is in a blank state. You can configure it
by adding roles, templates, and application frameworks that support basic
ecosystem functions.
1. Clone the application repository;
```shell
cd/opt/backenddir \
&& git clone https://github.com/ibax-io/dapps.git
```
2. Navigate to Developer> Import in Weaver;
3. Import applications as per the following order:
```
A./opt/backenddir/dapps/system.json
B./opt/backenddir/dapps/conditions.json
C./opt/backenddir/dapps/basic.json
D./opt/backenddir/dapps/lang_res.json
```
4. Navigate to Admin> Role, and click Install Default Role;
5. Exit the system through the configuration file menu in the upper right
corner;
6. Log in to the system as Admin;
7. Navigate to Home> Vote> Template List, and click Install Default Template.
### Add the first node to the node list {#add-the-first-node-to-the-node-list}
1. Navigate to Developer> Platform Parameters, and click the first_nodes
parameter;
2. Specify the parameters of the first blockchain network node.
- public_key - The public key of the node is located in the
`/opt/backenddir/node1/NodePublicKey` file;
```
{"api_address":"http://192.168.1.1:7079","public_key":"%node_public_key%","tcp_address":"192.168.1.1:7078"}
```
## Add other honor nodes {#add-other-honor-nodes}
### Add members into the consensus role group {#add-members-into-the-consensus-role-group}
By default, only members in the consensus role (Consensus) group can participate
in the voting required to add other master nodes. This means that before adding
a new master node, members of the ecosystem must be assigned to the role.
In this section, the creator's account is designated as the only member of the
consensus role group. In a production environment, this role must be assigned to
platform members that perform governance.
1. Navigate to Home> Role and click Consensus;
2. Click Assign to assign the creator's account to the role.
### Create the owner account for other nodes {#create-the-owner-account-for-other-nodes}
1. Run Weaver;
2. Import the existing account using the following data:
– Load the backup of the node owner's private key located in the
`/opt/backenddir/node2/PrivateKey` file.
3. After logging in to the account, since no role has been created at this time,
please select the Without role option.
4. Navigate to Home> Personal Information, and click the title of the personal
information;
5. Add account details (personal information title, description, etc.).
### Assign the node owner with the Validators role {#assign-the-node-owner-with-the-validators-role}
1. Operations by the new node owner:
1. Navigate to Home> Verifier;
2. Click Create Request and fill in the application form of the verifier
candidate;
3. Click send request.
2. Operations by the creator:
1. Log in with a consensus role (Consensus);
2. Navigate to Home> Verifier;
3. Click the "Play" icon to start voting according to the candidate's
request;
4. Navigate to Home> Vote, and click Update voting status;
5. Click the voting name and vote for the node owner.
As a result, the account of the owner of the new node is assigned with the
Validator role, and the new node is added to the list of master nodes.
---
## File: docs/concepts/about-the-platform.md
# IBAX Overview
- [Features](#features)
- [Architecture](#architecture)
- [Network](#network)
- [Honor Node](#honor-node)
- [Transactions](#transactions)
- [Network protocol](#network-protocol)
- [Block and transaction verification](#block-and-transaction-verification)
- [Database](#database)
- [ECOLIB](#ecolib)
- [IDE](#ide)
- [Applications](#applications)
- [Tables](#tables)
- [Ecosystem Parameters](#ecosystem-parameters)
- [Access rights control mechanism](#access-rights-control-mechanism)
- [Access Control Actions](#access-control-actions)
- [Access rights management](#access-rights-management)
- [Exclusive rights](#exclusive-rights)
- [Virtual private ecosystem](#virtual-private-ecosystem)
- [Requests to web resources](#requests-to-web-resources)
- [Rights to read data](#rights-to-read-data)
- [CLB creation](#clb-creation)
- [CLB usage](#clb-usage)
import Highlight from '@site/src/components/Highlight';
## Features {#features}
The IBAX Network (IBAX) has an integrated application development environment
(IDE). It is a multi-level access control system for data, user pages and smart
contracts.
In terms of its structure and functions, IBAX is quite different from most
existing blockchain platforms:
- The development and use of IBAX applications are in an autonomous software
environment called **ecosystem**. Each ecosystem has its own membership rules
that are initially established by the creator;
- Ecosystem activities, such as the data involved in
database table records or updates, are
based on **registers** created with **smart contracts**. In most other
blockchain platforms, activities are based on transaction exchange between
accounts;
- The access to **registers** and the control of relationships between ecosystem
members are managed by a set of rules called **smart laws**.
## Architecture {#architecture}
### Network {#network}
IBAX is built on a peer-to-peer (P2P) network.
Guardian nodes in the network store the latest version of the blockchain
database, which records the latest status of IBAX's blockchain.
Network users can receive data by sending requests from the guardian node
database via **Weaver** or REST API commands. After signing by users, new
requests are sent to the network as transactions in binary format. Essentially,
these transactions are commands to modify relevant database records.
Transactions are aggregated in blocks, and such blocks are sent to the
blockchains of all network nodes. Each guardian node will process the
transactions in the block, thereby updating the corresponding data in the
database.
### Honor Node {#honor-node}
A guardian node which is privileged to generate new blocks in the network is
called a honor node. The maximum number of honor nodes is defined by
[number_of_nodes](../reference/platform-parameters.md#number-of-nodes) in the
platform parameters table, showing that the number of honor nodes is limited.
An Honor Node is one of the key components of IBAX Public Network. It executes
and validates transactions, collects transaction information from other nodes,
adds transactions to the queue, and verifies the correctness and validity of new
blocks using the confirmation mechanism. Generally, it has two states: packaging
and non-packaging.
An Honor Node in the packaging state delivers the highest performance. It
obtains transaction requests to be executed from the transaction queue and
verifies the ignature validity and correctness of transactions, e.g. transfer
amount, permission for transaction operations, and accurate execution of
transactions.
All ransactional operations, correct or wrong (wrong transactions will be rolled
back), will be written into the block.
Wrong transactions will incur a punitive gas fee. Executed transactions are
notified to other Honor Nodes along with the block through broadcasting.
An Honor Node in the non-packaging state is mainly responsible for block
verification to ensure in-block transactions generated by a packaging node are
executed orrectly. In case of an anomaly, it will trigger the exception handling
mechanism and IBAX Network will roll back and re-verify the block.
In order to ensure transaction execution efficiency, Honor Nodes collect
transaction information constantly.
### Transactions {#transactions}
Transactions, including data used to implement **smart contracts**, are
generated by Weaver.
Transactions are signed by users with a private key. The private key and
Weaver's signature function can be stored in browsers, software clients, SIM
cards or dedicated physical devices. In the current implementation, the private
key is encrypted with the ECDSA algorithm and stored at the Weaver side. All
transactions are signed with the ECDSA algorithm.
The structure of a transaction complies with the following format:
- ID - ID of the contract implemented;
- Params - parameters sent to the contract;
- KeyID - ID of the user sending the transaction;
- PublicKey - public key of the honor node;
- Time - timestamp generated by the transaction;
- EcosystemID - ID of the ecosystem where the transaction is made;
- ТokenEcosystem - ID of the ecosystem, 1 by default, and tokens within it are
used to cover the transaction costs.
### Network protocol {#network-protocol}
Transactions will be sent to honor nodes by users, where they are subject to
basic verification to ensure the formats are correct and then are added to the
queue.Transactions are also sent to other honor nodes on the network and added
to the respective queue.
A honor node is privileged to generate new blocks within a specific time period
which is determined by the platform parameter **full_nodes** and a special
algorithm. Honor nodes retrieve transactions from queues and send them to the
block generator.
When generating a new block, transactions in such block will also be processed:
each transaction is sent to a virtual machine, where the contract corresponding
to the transaction parameters is implemented, thereby updating records in the
database.
New blocks should be verified to ensure there are no errors before sending to
other honor nodes on other networks.
A new block will be added to the block queue when received by other honor node
and, after verification, to the blockchain of the honor node where it is located
to process transactions in the block, and thereby updating records in the
database.
### Block and transaction verification {#block-and-transaction-verification}
After generating or receiving a new block, it will be verified on all other
honor nodes, which cover the following:
- The first byte of the data received should be 0. If not, the data received
will not be considered as a block;
- The received block generation timestamp should be before the current
timestamp;
- The block generation timestamp should correspond to the time interval at which
the honor node having privilege to generate new blocks;
- The height of a new block should be greater than the height of the largest
block on the existing blockchain;
- It cannot exceed the maximum expenses allowed for all transactions in the
block;
- The block must be properly signed with the secret key of the node which it is
located. The signature data should contain:
- The height of the block, the hash of the previous block, the timestamp of
the block, the ID of the ecosystem where the block is located, and the
account address of the honor node of the block;
- The position of the honor node in the platform parameter full_nodes array,
the Merkel Root (MrklRoot) of all transactions in the block, and the revert
hash of the previous block.
To check the correctness of each transaction in the block with the following
methods:
- The hash of each transaction must be unique;
- A key-signed transaction cannot exceed the limit
([max_tx_block_per_user](../reference/platform-parameters.md#max-tx-block-per-user));
- It cannot exceed the limit of the maximum transaction size
([max_tx_size](../reference/platform-parameters.md#max-tx-size));
- The transaction time can neither be greater than the block generation time or
be greater than the block generation time plus 600 seconds, and it can be no
less than the block generation time minus 86400 seconds;
- The transaction must be signed properly;
- The user who implements the contract must have sufficient tokens in his
account to pay for the transaction cost.
### Database {#database}
The underlying data storage layer of IBAX Network is a `PGSQL` database
completely open to the public. Based on the permission design of the IBAX
Operating System Platform, users do not need to worry about data security. With
an object-oriented design philosophy, IBAX Network pre-compiles data through a
relational PGSQL database and improves the data processing efficiency.
You may be interested in the following if you are a technical specialist, or
just skip it if you are not. ① All tables without a number prefix in their name
belong to permission tables of IBAX Network Basic; ② All tables with a number
prefix in their name belong to permission tables of ecoLibs.
## ECOLIB {#ecolib}
It is quite easy for users, even common users, to create an ecoLib of their own
on the IBAX Network System Platform. We have integrated and developed an
application where ecoLib creation takes just one click.
When creating an ecoLib, you can configure the ecosystem parameters and rules,
and set the administrator account and charging model. Most importantly, to apply
the DPoA consensus within ecoLibs better, creators can set it up by writing or
importing their own contracts.
We support quick emission of ecoLib tokens by importing contract templates.
Due to the differences in consensus and management permissions, ecoLibs fall
into decentralized and centralized ones. They have no specific advantage or
disadvantage by type. You should choose the appropriate one against your service
needs. What to do if it is OK for now but not for the future? You can change
ecoLib parameters, even the consensus mechanism, token, and governance method,
on the IBAX Network System Platform. You can leave it all to the self-governance
mechanism maintained by the ecoLib administrator or members (depending on the
ecoLib type).
On the IBAX Network System Platform, an ecoLib has complete data control
permissions and permissions to design and access independent database tables and
fields. In the data control permission design, we support triggering when a
field satisfies a logical expression. This feature allows for imagination space
in special services like monitoring, logic satisfaction, and triggering by time
and specific conditions.
There may be multiple DApps in an ecoLib, and each of them can have independent
parameters. An ecoLib is like a platform where you can implement anything you
want.
In order to better support ecosystem developers, we provide the editing,
management, and development tool Weaver. It will reduce the ecosystem
development, maintenance, and management costs greatly.
### IDE {#ide}
Weaver has a complete integrated development environment (IDE) for creating
blockchain applications, which does not require software developers to have a
deep understanding of the blockchain technology.
Weaver provides a table management tool, contract editor, page editor and other
functions needed to create applications in the ecosystem, without the support of
any software module.
The IDE mainly includes the following parts:
- list of ecosystem parameters;
- contract editor;
- table management tool;
- page editor and visual page designer;
- multi-language resources editor;
- application import/export functions.
### Applications {#applications}
An application is a collection of elements such as database tables, smart
contracts, and user pages with access rights for configuration. The ecosystem to
which the application element belongs is indicated by the prefix in the element
name, such as @1ElementName, where the
ecosystem ID is indicated by the number 1
after the @ symbol. When using application
elements in the current ecosystem, the prefix
@1 can be omitted. These applications can
perform useful functions or implement various services.
### Tables {#tables}
In IBAX's database, each ecosystem can create an unlimited number of tables.
Tables of a specific ecosystem can be identified by a prefix containing the
ecosystem ID, which will not be displayed in Weaver.
A table is not bound in any way and belongs to a certain contract. It can be
used by all applications within the scope of the table's access rights.
Each ecosystem can create a set of data tables for developing its applications
or may, possibly, access data tables of other ecosystems by specifying the table
name prefix.
By configuring access rights through smart laws, data are logged into tables.
Smart laws are used for rights management.
> Table management tool
You can find the table management tool in Weaver **menu Table**, which cover the
following functions:
- View the list of tables and their entries;
- Create new tables;
- Add a table field and specify its data type, such as `Text` ， `Date/Time` ，
`Varchar` , `Character` ， `JSON` ， `Number` ， `Money` ， `Double`
，`Binary`；
- `Text` correspond `postgresql` `text`
- `Date/Time` correspond `postgresql` `timestamp`
- `Varchar` correspond `postgresql` `varchar(102400)`
- `Character` correspond `postgresql` `character(1) NOT NULL DEFAULT '0'`
- `JSON` correspond `postgresql` `jsonb`
- `Number` correspond `postgresql` `bigint NOT NULL DEFAULT '0'`
- `Money` correspond `postgresql` `decimal (30, 0) NOT NULL DEFAULT '0'`
- `Double` correspond `postgresql` `double precision`
- `Binary` correspond `postgresql` `bytea NOT NULL DEFAULT '\x'`
- Manage privileges for insert, update data and change table structure.
> Table data manipulation
For better database manipulation, both Needle and Logicor have the **DBFind**
function, which is used to retrieve values and data arrays from tables.
The contract language [DBInsert](../topics/script.md#dbinsert) function is used
to add entries to tables. The [DBUpdate](../topics/script.md#dbupdate)
and[DBUpdateExt](../topics/script.md#dbupdateext) functions are used to update
the value of an existing entry. During updating, the corresponding data in
tables will be updated, and the blockchain will add new transactions while
retaining all historical transactions. Data in tables can only be modified and
cannot be deleted.
In order to minimize the contract implementation time, the
[DBFind](../topics/script.md#dbfind) function cannot query multiple tables
simultaneously, and JOIN is not supported. Therefore, we recommend not to
normalize application tables, but to store all available information in entries
or repeat the information available in other tables. This is not mandatory but
necessary for a blockchain application. In this case, data should be stored
fully, which cannot be updated even if the same data in other tables is updated,
though it is updated synchronously in a relational database.
### Ecosystem Parameters {#ecosystem-parameters}
You may view and edit the list of ecosystem parameters (**1_parameters**) in
Weaver's menu. Ecosystem parameters can be divided into the following groups:
- General parameters: the account of the ecosystem creator (founder_account) and
other information;
- Access rights parameters: used to define access permissions for application
elements
- change the table structure (changing_tables);
- change the contract (changing_contracts);
- change the user page (changing_page);
- change the menu (changing_menu);
- change the multi-language resources (changing_language).
- Technical parameters: used to define the user styles (stylesheet);
- User parameters: used to define constants or lists (separated by commas)
required for application operation.
You may specify the edit permission for parameters of each ecosystem.
You may use the [EcosysParam](../topics/script.md#ecosysparam) function to
retrieve the value of an ecosystem parameter by passing the ecosystem parameter
title as a parameter to it.
## Access rights control mechanism {#access-rights-control-mechanism}
IBAX has a multi-level access permission management system. By configuring
access rights, you can create and change any application element, such as the
contracts, tables, user pages, ecosystem parameters. You may also change the
access rights through configuration.
By default, all rights in the IBAX ecosystem are managed by its creator, which
is defined in the MainCondition contract of each ecosystem. But after creating
smart laws, access control can be transferred to all or a group of ecosystem
members. Access rights control
### Access Control Actions {#access-control-actions}
The access rights are defined in contract tables (**1_contracts** ), data tables
(**1_tables** ), user page tables (**1_pages** ), menu tables (**1_menu** ), and
code block tables (**1_blocks** ). You can find the corresponding menus in
Weaver.
### Access rights management {#access-rights-management}
The rules of access rights are configured by filling in the corresponding
contract expressions **ContractConditions(“@1MainCondition”)**,
**ContractAccess(“@1MainCondition”)** or logical expressions in the permission
field. If the result of the request expression passes (true ), then access is
granted. Otherwise, access is denied and related operations are terminated.
The easy way to define rights is to enter a logical expression in the right
field. For example, `$key_id == 8919730491904441614`, where **$keyid**
represents the ID of an ecosystem member.
The most common and recommended way to define rights is to use the
`ContractConditions("@1ContractsName1","@1ContractsName2")` function. The
contract name **ContractsName** is passed to the function as a parameter, and
the contract result must be the result of a logical expression (true or false).
Another way to define rights is to use the
`ContractAccess("@1ContractsName3","@1ContractsName4")` function. The contract
**ContractsName** qualified to implement the corresponding operation can be
passed to the function as a parameter. For example, if the right field of the
amount column is configured as `ContractAccess("@1TokenTransfer")`, then you can
only implement the contract **@1TokenTransfer** if you want to change the value
in the amount column. The right to access the contract itself can be managed in
the conditions section, which are quite complex and may contain many other
contracts.
### Exclusive rights {#exclusive-rights}
In case of emergencies or situations that are critical to the operation of an
ecosystem, there are many special parameters in the list of ecosystem parameters
(**1_parameters**) (such as **changing_contracts**、**changing_pages**), etc.,
which defines rights to access all contracts, data tables, and pages of the
current ecosystem. These rights are configured by key contracts.
## Virtual private ecosystem {#virtual-private-ecosystem}
In IBAX, you can create a virtual private ecosystem - **Cross Ledgers Base
(CLB)**. A CLB has the full functionality of the standard ecosystem, but
operates outside the blockchain. In CLB, you can use and create contracts and
template languages, tables, and use Weaver to create applications. You may call
contracts on the blockchain ecosystem via API.
### Requests to web resources {#requests-to-web-resources}
CLB
> The main difference between a CLB and a standard ecosystem is that you can use
> contract functions [HTTPRequest](../topics/script.md#httprequest) and
> [HTTPPostJSON](../topics/script.md#httppostjson) to request any web resource
> within the contract via **HTTP / HTTPS** requests. Parameters passed to this
> function include: URLs, request methods (GET or POST), request headers and
> request parameters.
### Rights to read data {#rights-to-read-data}
Though it is readable, data in CLB is not saved within the blockchain. You can
choose to grant the read permission to database tables. You can set rights to
read for individual columns, or for any row using a special contract.
### CLB creation {#clb-creation}
You may create a CLB node on the network. As predefined, the CLB node
administrator is privileged to use the ecosystem list with the CLB
functionality, and designate a user with ecosystem creator privileges to install
applications, receive new members and configure the resources access
permissions.
### CLB usage {#clb-usage}
You may use a CLB to create registration forms, send verification information to
users via email or phone, and store publicly accessible data. You can write and
test applications, and then import them into the blockchain ecosystem. In a CLB,
you may use scheduling contract tasks, create oracle machines to receive data
from web resources and send such data to the blockchain ecosystem.
---
## File: docs/concepts/blockchain-layers.md
# The IBAX Network
In this section, we will brief you how to use IBAX.
- [Application developers](#application-developers)
- [ECOLIB members](#ecolib-members)
- [ECOLIB applications and platform applications](#ecolib-applications-and-platform-applications)
- [Underlying model](#underlying-model)
- [Implementation](#implementation)
If you are interested in the development, use or management of applications in
IBAX, then you may not need to understand it at all.
In IBAX, the blockchain and the blockchain network are hidden from ECOLIB
members, administrators, and application developers. IBAX offers
[RESTful API](../reference/api2.md) for all user groups, which provide a
tamper-proof and distributed access to the **global state** of the blockchain.
## Application developers {#application-developers}
In technical terms, the **global state** is a set of data, which is implemented
via IBAX's database. From the perspective of application developers, an
application interacts with the database by querying, inserting and updating
tables.
In IBAX, transactions are written into the blockchain by implementing various
contracts. These transactions will call contract codes implemented by blockchain
network nodes, which will update the global state (database) accordingly.
For application developers, a contract is a function that data will be written
to the database when it is implemented. Pages are like scripts and the page code
is a set of page [template](../topics/templates2.md) functions, some of these
functions display page elements, while other data comes from the database.
Application developers do not need to understand what are transactions, block
generation and consensus algorithms, just use it.
## ECOLIB members {#ecolib-members}
Applications written by developers run in an environment called
[ECOLIB](thesaurus.md#ecolib). An application usually serves a specific purpose
and complete various tasks together with several other applications.
A user must become a member of an ECOLIB if wants to access applications in it,
and it can be a member of multiple different ECOLIBs at the same time.
ECOLIB members can view and modify the database from application pages, just
like filling out forms, clicking buttons and navigating pages in a common web
application.
## ECOLIB applications and platform applications {#ecolib-applications-and-platform-applications}
Applications may fall into **ECOLIB applications** and **platform
applications**.
> ECOLIB applications
An ECOLIB application implements certain unique functions or business processes
of an ECOLIB, but it is only available in that ECOLIB.
> Platform applications
A platform application is applicable to all ECOLIBs. Any application could be
developed as a platform application. IBAX developers would provide platform
applications that support the core functions for ECOLIB governance, such as
voting, notification, and ECOLIB member role management.
## Underlying model {#underlying-model}
> Definition of layers
IBAX consists of several layers:
- User interaction layer
ECOLIB members interact with the application through pages and page elements.
- Application layer
Application developers interact with the global state (data tables) through
contract codes and page codes.
- Global state layer
Update and synchronize the global state (database) based on operations written
to the distributed ledger (blockchain)
- Blockchain layer
Update the distributed ledger with new blocks. Operations (transactions) saved
in new blocks must be performed on the global state.
- Node network layer
It implemented the IBAX Network protocol, which distributes, verifies
transactions and generates new blocks on the node network. Similarly, new
blocks are distributed and verified by the node network.
The distributed ledger of all nodes is kept in sync. If having conflicts in a
node, the node will identify which blockchains are considered valid and
invalid blockchains will be rolled back accordingly.
- Transaction layer
Transactions are the basis for generating blocks and blockchain protocols, and
transactions themselves are the results of operations performed at the user
interaction layer. Transactions are generated by Weaver.
When a user or developer performs an operation such as clicking a button on a
page or implement a contract from the code editor, Weaver will convert this
operation into a transaction and send it to the network node connected to it.
Therefore, the flow of transactions is as follows:
- A user operation in a user page will become a transaction;
- The transaction is contained in a block;
- The block is included in the blockchain;
- The change of operation will cause the global state of the blockchain to
change, and such operation will be applied to the database;
- Any database change will be reflected in the application.
## Implementation {#implementation}
IBAX has two major components, i.e. server
[go-ibax](https://github.com/IBAX-io/go-ibax) and Weaver
[Source code](https://github.com/IBAX-io/weaver).
Weaver:
- Providing the user pages;
- Providing the IDE for application development;
- Storing public keys of user accounts and perform authorization;
- Requesting database data from application pages and display application pages
to users;
- Sending transactions to the server through [REST APIs](../reference/api2.md);
In order to automatically create transactions against user operations, Weaver
will convert such operations into transactions when application developers
implement a contract from the IDE.
Server:
- Keeping the global state (database) of the node;
- Implementation of the blockchain protocol;
- Implementation of contract codes in the IBAX
[Virtual Machine](../topics/vm.md);
- Implementation of page codes in the
[Template Engine](../topics/templates2.md);
- Implementation of [RESTful API](../reference/api2.md).
---
## File: docs/concepts/consensus.md
# Decentralized Proof-of-Authority Consensus {#decentralized-proof-of-authority-consensus}
- What is Decentralized Proof-of-Authority consensus
- Advantages of DPoA consensus
- DPoA consensus and common means of attack
- Implementation of DPoA consensus in IBAX
In this section, we will describe the Decentralized Proof-of-Authority consensus
and its implementation in IBAX.
- [What is Decentralized Proof-of-Authority consensus](#what-is-decentralized-proof-of-authority-consensus)
- [Advantages of DPoA consensus](#advantages-of-dpoa-consensus)
- [DPoA consensus and common means of attack](#dpoa-consensus-and-common-means-of-attack)
- [DoS](#dos)
- [51 percent attack](#percent-attack-51)
- [Implementation of DPoA consensus in IBAX](#implementation-of-dpoa-consensus-in-ibax)
- [Honor node](#honor-node)
- [Leader node](#leader-node)
- [Generation of new blocks](#generation-of-new-blocks)
- [Forks](#forks)
## What is Decentralized Proof-of-Authority consensus {#what-is-decentralized-proof-of-authority-consensus}
Considering commercial application scenarios and real-world environments, IBAX
Network has built a new consensus mechanism, DPoA (Decentralized Proof of
Authority).
Decentralization has always been our firm belief. It refers not only to IBAX’s
infrastructure network environment. Instead, we will let decentralization take
root in each ecoLib created in IBAX Network and use technical solutions to
achieve a high degree of self-governance in each of them. For the purpose of
highly distributed self-governance, we have made many changes in the overall
architecture and technical implementation. However, in practice, we cannot avoid
the centralized management concept. In order to find a balance between
centralization and decentralization, in addition to the DPoA consensus
mechanism, we have also formulated certain reward and incentive programs.
IBAX Network has created a new consensus mechanism that combines distribution,
weak centralization, and a certification authority. We call it DPoA
(Decentralized Proof of Authority). To ensure continuity for the entire IBAX
Network, the consensus covers not only IBAX Public Network, but also ecoLibs
created by each user and user group. This creates a truly self-governed,
decentralized, fair, transparent, and fraud-proof Decentralized Autonomous
Organization (DAO).
DPoA has a prevention mechanism against network attacks and allows creation of
Mint Nodes that guard the network and mint new IBXC coins. IBAXCoin holders can
stake a part of their IBXC liquidity balance in Mint Nodes for Mint & Stake
Emission Rewards. Minting and staking serve to increase the cost and difficulty
of attacks and increase the total value of IBXC coins proportionally. With this
mechanism, the probability and harm of any attack are infinitely close to zero.
## Advantages of DPoA consensus {#advantages-of-dpoa-consensus}
Compared to Proof-of-Work (PoW) or Proof-of-Stake (PoS) consensus, DPoA
consensus has the following advantages:
- No need of high-performance hardware. Compared to PoW consensus, nodes
implementing the DPoA consensus does not spend computational resources for
solving complex mathematical logic tasks;
- The interval of time to generate new blocks is predictable, but that for PoW
and PoS consensuses are different;
- High transaction rate. Blocks are generated in a sequence at specified time
interval by authorized network nodes, which increases the speed of transaction
verification.
- Tolerance to compromised and malicious nodes, as long as 51% of nodes are not
compromised. IBAX implements a mechanism of banning nodes and revoking block
generation rights.
## DPoA consensus and common means of attack {#dpoa-consensus-and-common-means-of-attack}
### DoS {#dos}
An attacker may send large amount of transactions and blocks to a targeted node
in the network, making an attempt to disrupt its operation and make its services
unavailable.
The DPoA mechanism is possible to defend against DoS attacks:
- Because network nodes are pre-authenticated, block generation rights can be
granted only to nodes that can withstand DoS attacks.
- If a honor node is unavailable for a certain period, it can be excluded from
the list of honor nodes.
### 51% attack {#percent-attack-51}
As to the scenario with the DPoA consensus, the 51% attack requires an attacker
to obtain control over 51% of network nodes. But the scenario for the PoW
consensus is different, which an attacker needs to obtain 51% of network
computational power. Obtaining the control over nodes in a permissioned
blockchain network is much harder than obtaining the computational power.
For example, in a network implementing the PoW consensus, an attacker can
increase computation power (performance) of the controlled network segment thus
increasing the percentage of controlled nodes. This makes no sense for DPoA
consensus, because the computational power of the node has no impact on the
blockchain network decisions.
## Implementation of DPoA consensus in IBAX {#implementation-of-dpoa-consensus-in-ibax}
### Honor node {#honor-node}
In IBAX, only honor nodes can generate new blocks, which maintain the blockchain
network and the distributed ledger.
The list of honor nodes is kept in the blockchain registry. The order of nodes
determines the sequence in which nodes generate new blocks.
### Leader node {#leader-node}
The leader node is the honor node that generates a new block at the current
time. The following formula determines the leader node in the current honor node
list:
```text
leader = ((time - first) / step) % nodes
```
> leader
Current leader node.
> time
Current time (UNIX).
> first
First block generation time (UNIX).
> step
Number of seconds in the block generation interval.
> nodes
Total number of honor nodes.
#### Generation of new blocks {#generation-of-new-blocks}
New blocks are generated by a [leader node](#leader-node) of the current time
interval. At each time interval, the leader role is passed to the next honor
node from the list of honor nodes.
a) Steps for Generation of new blocks
Main steps for generating a new block are as follows:
1. Collects all new transactions from the transaction queue of the node;
2. Executes transactions one by one. Invalid or inexecutable transactions are
rejected;
3. Checks if the
[block generation limits](../reference/platform-parameters.md#configure-the-generation-of-blocks)
is in compliance;
4. Generates a block with valid transactions and signs it with the private key
of the honor node through the ECDSA algorithm;
5. Sends this block to other honor nodes.
b) Verification of new blocks
Steps for verifying new blocks on other honor nodes:
1. Receive a new block and verify:
– whether the new block was generated by the leader node of a current
interval;
– whether there are no other blocks generated by the leader node of a current
interval;
– whether the new block is properly signed.
2. Execute transactions from the block one by one. Check whether the
transactions are executed successfully and within the
[block generation limits](../reference/platform-parameters.md#configure-the-generation-of-blocks)
.
3. Add or reject the block, depending on the previous step:
– If block validation is successful, add the new block to the blockchain of
the current node;
– If block validation failed, reject the block and send a **bad block**
transaction;
– If the honor node that created this invalid block continues to generate bad
blocks, it can be banned or excluded from the list of honor nodes.
### Forks {#forks}
A **fork** is an alternative version of the blockchain, which contains one or
more blocks that were generated independently from the rest of the blockchain.
Forks usually occur when a part of the network becomes desynchronized. Factors
that are probably result in forks are high network latency, intentional or
unintentional time limits violation, time desynchronization at nodes. If network
nodes have a significant geographic distribution, block generation interval must
be increased.
Forks are resolved by following the longest blockchain rule. When two blockchain
versions are detected, honor nodes rollback the shorter one and accept the
longer one.
---
## File: docs/concepts/faq.md
# FAQ {#faq}
import TOCInline from '@theme/TOCInline';
## 1. Please briefly describe IBAX? {#question-1}
- It is a blockchain platform that aims to build a digital ecosystem based on an
integrated application development environment that has a multi-level
permission system for managing the access rights to data, interfaces, and
smart contracts.
## 2. Is IBAX applicable for Bitcoin, Ethereum or other blockchains? {#question-2}
- Not applicable. IBAX is built on the basis of its own original blockchain.
## 3. What are the main differences between IBAX and other public blockchain platforms with built-in mechanisms for executing smart contracts? {#question-3}
- IBAX has unique features that cannot be found in the above-mentioned
blockchains:
- has an integrated application development environment in a single client
software;
- the special template language Logicor for page design and the contract
language Needle coordinate with each other;
- has a multi-level permission system for managing the access rights to data,
interfaces and smart contracts, in which permissions can be granted to
members, roles and contracts;
- the ecosystem, used to create blockchain applications and autonomous
software environments for users to interact with them;
- the legal system, a set of rules written in smart laws (dedicated smart
contracts), regulates the relationship between platform users and defines
the process of changing protocol parameters for problem solving.
## 4. Do you have your own cryptocurrency? {#question-4}
- Yes, IBAX uses its own token, IBXC.
## 5. What is a honor node and who can maintain it? {#question-5}
- The honor node is the network node that has the authority to verify
transactions and generate new blocks.
- Any network node with sufficient processing power and fault tolerance can
become a honor node. IBAX uses a Proof of Authority (PoA) consensus mechanism.
Nodes can become verification nodes based on ecosystem voting, but only
ecosystems that are proven by the platform's token owner to have normal
operational capabilities can participate in such voting. Using this
authorization algorithm, the master node is run by major ecosystems because it
is in their best interest to maintain the network operation.
## 6. What is a platform ecosystem? {#question-6}
- An ecosystem is actually an autonomous software environment used to create
blockchain applications and the operations of users in them.
## 7. Who can create an ecosystem? {#question-7}
- All users of the platform can create new ecosystems.
## 8. How do users become members of the ecosystem? {#question-8}
- Users may be registered as members of any existing ecosystem. The ecosystem
strategy defines different member admission procedures, which publishes key
public information of the new ecosystem in a dedicated ecosystem catalog.
## 9. Can one user create multiple ecosystems? {#question-9}
- Yes, each user can create any number of ecosystems and can also become a
member of multiple ecosystems.
## 10. What is a platform application? {#question-10}
- An application is a complete software product that implements a function or
service. The application consists of database tables, contracts and pages.
## 11. What programming language is used to create the application? {#question-11}
- The contract is written in the Needle language, which is developed by the
platform team, For more information, see:
[Smart Contract](../topics/script.md).
- The page is written in Logicor language, which is a page template language.
For more information, see: [Template Language](../topics/templates2.md).
## 12. What software is used to create applications and interact with users? {#question-12}
- The application program is written and executed in Weaver, no other software
is required.
## 13. Can platform contracts use third-party APIs to access data? {#question-13}
- No, the contract can only directly access the data stored in the blockchain.
[CLB](about-the-platform.md#virtual-private-ecosystem) is used to process
external data sources.
## 14. Can the contract stored in the blockchain be changed? {#question-14}
- Yes, the contract can be changed. The permission to change the contract is
specified by its creator, who can grant the permission to refuse to change, or
grant permission to make changes with contracts or by members, or configure a
complex set of conditions in the smart law.
- Weaver provides access to all versions of contracts.
## 15. What is smart law? {#question-15}
- Smart law is a contract designed to control and restrict the operation of
conventional contracts, thereby controlling and restricting the activities of
ecosystem members.
- A set of smart laws can be regarded as the legal system of an ecosystem.
## 16. Can the contract call and execute other contracts? {#question-16}
- Yes, the contract can call other contracts by direct addressing and provide
parameters for it, or call the contract by link name. For more information,
see: [Smart Contract](../topics/script.md).
## 17. Does the application run with a master contract? {#question-17}
- No, the contract is an autonomous program module that performs certain
functions. Each contract is configured to receive specified data, then check
the correctness of these data, and perform some operations that are recorded
in the database as transactions.
## 18. Can the application be localized for different languages? {#question-18}
- Yes, Weaver has a built-in localization support mechanism and can create pages
in any language.
## 19. Can I create a page without using a template language? {#question-19}
- Yes, it can be done using the platform [RESTful API](../reference/api2.md) v2.
## 20. Are the pages stored in the blockchain? {#question-20}
- Yes, the pages and contracts are stored in the blockchain, which prevents them
from being forged.
## 21. What types of databases can be used for contract operations? {#question-21}
- Currently, PostgreSQL is used.
## 22. How to manage access to the data in the database table? {#question-22}
- You can add new fields, new entries, or change the permissions of the data in
columns for ecosystem members, roles, or specified contract configurations.
Except for contracts created by performing specific operations.
## 23. Can an application in an ecosystem exchange data with other applications from another ecosystem? {#question-23}
- Yes, data exchange can be organized through global data tables that apply to
all ecosystems.
## 24. Should all applications in a new ecosystem be written from scratch? {#question-24}
- No, every new ecosystem has some applications out of the box:
- A mechanism to manage ecosystem members and roles;
- Issuing and configuring other tokens;
- A voting system;
- A notification system;
- A messenger between ecosystem members.
These applications can be edited and configured to meet the special needs of any
ecosystem.
## 25. Are there any fees for the operation of applications? {#question-25}
- Yes, the use of the resources of the honor node requires payment in the
platform.
## 26. Who pays for the operation of applications? {#question-26}
For corresponding account addresses, there are currently 4 ways to pay for the
operation of applications:
- For contract callers, the fee will be paid from the user's account by default
when the user calls the contract;
- For contract binding parties, the fee will be paid from the binding account
specified by the contract creator;
- For ecosystem creators, the fee of all applications within an ecosystem will
be paid by the ecosystem creator respectively;
- Exclusive ecosystem wallet. Each ecosystem has an exclusive account. If the
ecosystem creator activated it, the fee of all applications within the
ecosystem will be paid from this account.
Order of payment precedence: Exclusive ecosystem wallet> Ecosystem creator>
Contract binding party> Contract caller.
## 27. How to protect the applications in the ecosystem from attacks due to vulnerabilities? {#question-27}
- The platform team also knows that there is no way to completely avoid errors
in the application code, especially considering that the application can be
written by any user. This is why we decided to establish a mechanism to
eliminate the consequences of exploiting vulnerabilities. The legal system can
stop the attack operation of the application and use some transactions to
restore it to its original state. The legal system stipulates the permissions
to execute such contracts and the voting procedures for granting these
permissions.
## 28. What new features will be implemented in future plans? {#question-28}
- Visual smart contract designer;
- Support for hybrid databases (SQL and NoSQL);
- Parallel multi-threaded processing of transactions from different ecosystems;
- Perform resource-intensive calculations on the client;
- Ecosystem hosting and computing power exchange;
- Child nodes, only store some blocks on the server;
- Semantic references (ontology) are used to unify the operation of data in the
platform.
## 29. How to prove its operability? {#question-29}
- A number of proof of concept projects and cases have been implemented on the
IBAX Network: a socialized tax collection and electronic invoice generation
and circulation system, a medical apparatus and instruments supervision,
forgery prevention and tracing system, a financing and supervision system, a
voting/poll system, business registration, trade finance tools, assets
registration contract management system, etc.
---
## File: docs/concepts/thesaurus.md
# Terms and Definitions {#terms-and-definitions}
- [Blockchain terms](#blockchain-terms)
- [Blockchain](#blockchain)
- [Peer-to-peer network](#peer-to-peer-network)
- [Hash](#hash)
- [Block](#block)
- [Block verification](#block-verification)
- [Consensus](#consensus)
- [Token](#token)
- [Identification](#identification)
- [Unique identification](#unique-identification)
- [Private key](#private-key)
- [Public key](#public-key)
- [Digital signature](#digital-signature)
- [Smart contract](#smart-contract)
- [Transaction fee](#transaction-fee)
- [Double spend](#double-spend)
- [Encryption](#encryption)
- [Private blockchain](#private-blockchain)
- [Public blockchain](#public-blockchain)
- [Proof of Authority](#proof-of-authority)
- [IBAX Terms](#ibax-terms)
- [Testnet](#testnet)
- [Mainnet](#mainnet)
- [Gas fee](#gas-fee)
- [Account address](#account-address)
- [Wallet address](#wallet-address)
- [Weaver](#weaver)
- [ECOLIB](#ecolib)
- [ECOLIB parameters](#ecolib-parameters)
- [ECOLIB members](#ecolib-members)
- [Virtual private ECOLIB](#virtual-private-ecolib)
- [Decentralized Proof-of-Authority](#decentralized-proof-of-authority)
- [Needle](#needle)
- [Logicor](#logicor)
- [Integrated Development Environment (IDE)](#integrated-development-environment-ide)
- [Page editor](#page-editor)
- [Visual page designer](#visual-page-designer)
- [Contract editor](#contract-editor)
- [Multilingual resources](#multilingual-resources)
- [Application export](#application-export)
- [Application import](#application-import)
- [Smart law](#smart-law)
- [Legal system](#legal-system)
- [Application](#application)
- [Page](#page)
- [Code segment](#code-segment)
- [Access rights](#access-rights)
- [Honor node](#honor-node)
- [Guardian node](#guardian-node)
- [Concurrent transaction processing](#concurrent-transaction-processing)
## Blockchain terms {#blockchain-terms}
### Blockchain {#blockchain}
> Blockchain is an information system that stores data and transmits and
> processes data within the system to prevent data from being forged or lost
> while maintaining data reliability; Data protection is achieved by:
>
> > 1. writing data into a blockchain of a series of encrypted blocks;
> > 2. distributed storage of blockchain copies in peer-to-peer networks;
> > 3. synchronization of blockchains on all nodes using a consensus mechanism;
> > 4. ensuring data reliability when performing data operations using the
> > network with algorithms that store data transmissions and process
> > contracts in the blockchain.
### Peer-to-peer network {#peer-to-peer-network}
> A computer network, consisting of equally privileged nodes (without a central
> server).
### Hash {#hash}
> Also known as hashing, the binary value of any file or data set length that is
> mapped to a shorter fixed-length binary value.
### Block {#block}
> After verifying the format and signature of the transaction, a transaction set
> is grouped by the honor node into a specific data structure. A block contains
> a hash pointer as a link to the previous block, which is one of the measures
> to ensure the security of blockchain encryption.
### Block verification {#block-verification}
> A procedure to verify the correctness of the block structure, generation time,
> compatibility with the previous block, transaction signatures, and the
> correspondence between the transaction and the block data.
### Consensus {#consensus}
> The verification protocol or algorithm of this type of protocol used by the
> honor node in the process of adding new blocks to the blockchain.
### Transaction {#transaction-1}
> Data transmission operations on the blockchain network or records of such
> transactions in the blockchain.
### Token {#token}
> Proof of encrypted digital rights and shares that can be circulated on the
> blockchain. A set of identifiable digital records stored in a register,
> including a mechanism for exchanging rights and shares between these records.
### Identification {#identification}
> An encryption program used to identify users in the system.
### Unique identification {#unique-identification}
> The process of linking accounts with users requires legal and organizational
> efforts or other procedures to achieve biometric identification in order to
> link user names with actual users.
### Private key {#private-key}
> A string of characters secretly stored by its owner, used by the owner to
> access virtual accounts on the internet and sign transactions.
### Public key {#public-key}
> A string of characters used to check the authenticity of the private key. The
> public key is uniquely derived from the private key.
### Digital signature {#digital-signature}
> The attributes of a document or message obtained after encrypted data
> processing. The digital signature is used to check the integrity of the
> document (no modification) and authenticity (verification of the identity of
> the sender).
### Smart contract {#smart-contract}
> In the program that performs data storage operations in the blockchain, all
> contracts are stored in the blockchain.
### Transaction fee {#transaction-fee}
> The fee paid to the honor node to execute the transaction.
### Double spend {#double-spend}
> A method of attacking the blockchain network. The result is that a transaction
> costs the same token twice.
> This kind of attack occurs when the blockchain is forked, which can only be
> executed when the attacker controls more than 50% of the network's
> verification capability.
### Encryption {#encryption}
> A way of digital data conversion, only the party with the corresponding
> decryption key can read it.
### Private blockchain {#private-blockchain}
> A blockchain network where all nodes and data access rights are centrally
> controlled by a single organization (government, company or individual).
### Public blockchain {#public-blockchain}
> In a blockchain network that is not controlled by any organization, all
> decisions are made by reaching a consensus among network participants.
> Everyone can obtain and access the data of the blockchain network.
### Proof of Authority {#proof-of-authority}
> Proof of Authority (PoA), IBAX Network has created a new consensus mechanism
> that combines distribution, weak centralization, and a certification
> authority. We call it PoA (Proof of Authority). To ensure continuity for the
> entire IBAX Network, the consensus covers not only IBAX Public Network, but
> also ecoLibs created by each user and user group. This creates a truly
> self-governed, decentralized, fair, transparent, and fraud-proof Decentralized
> Autonomous Organization (DAO).
## IBAX Terms {#ibax-terms}
### Testnet {#testnet}
> The version of the blockchain network used for testing.
### Mainnet {#mainnet}
> The main version of the blockchain network.
### Transaction {#transaction-2}
> Call the contract and pass the parameters to the operation command of the
> contract. The result of the honor node execution is the update of the
> database.
### Gas fee {#gas-fee}
> A conventional unit used to calculate the cost of performing certain
> operations on a network of nodes. The fuel exchange rate is determined by a
> vote on the honor node.
### Account address {#account-address}
> The data records store the token and can be accessed through a pair of keys
> (private key and public key).
### Wallet address {#wallet-address}
> The character encoding identifier of the user on the node network that is used
> as the name of the user's virtual account.
### Weaver {#weaver}
> The software client used to connect to the node network, which provides the
> desktop and web browser versions.
>
> Weaver integrates the platform development environment, including creating and
> editing tables, pages, and contracts. Users can build ECOLIBs, create and use
> applications in Weaver.
### ECOLIB {#ecolib}
> A relatively closed or open software programming environment, including
> applications and ECOLIB members.
>
> ECOLIB members can issue exclusive tokens belonging to the ECOLIB, use smart
> contracts to establish interaction rules between members, and set access
> rights to application elements for members.
### ECOLIB parameters {#ecolib-parameters}
> A set of configurable ECOLIB parameters, such as the account of the creator of
> the ECOLIB and the permissions of changing application elements, can be
> changed in the parameter table.
### ECOLIB members {#ecolib-members}
> Users who can access specific ECOLIBs and application features.
### Virtual private ECOLIB {#virtual-private-ecolib}
> Virtual private ECOLIB - Cross Ledgers Base (CLB), which has the full set of
> functions of the standard ECOLIB, but works outside the blockchain. In CLB,
> you can use and create contracts and template languages, database tables, and
> use Weaver to create applications. You can call contracts on the blockchain
> ECOLIB via APIs.
### Decentralized Proof-of-Authority {#decentralized-proof-of-authority}
> Decentralized Proof-of-Authority (DPoA) is a new consensus algorithm that
> provides high performance and fault tolerance. In DPoA, the right to generate
> new blocks is granted to nodes that have proven the right to do so, and such
> nodes must be subject to preliminary verification.
### Needle {#needle}
> A scripting language used to create smart contracts that can handle data
> received from user pages and value operations performed in database tables.
>
> You can create and edit contracts in Weaver's editor.
### Logicor {#logicor}
> The template language used to create pages. It can get values from database
> tables, build user pages, and pass user input data to the **data** section of
> the contract.
### Integrated Development Environment (IDE) {#integrated-development-environment-ide}
> Integrated Development Environment (IDE) is a set of software tools used to
> create applications.
>
> Weaver's IDE includes a contract editor, page editor, database table
> management tool, multi-language resources editor, as well as application
> export and import functions. The IDE complements the visual page designer
> based on semantic tools.
### Page editor {#page-editor}
> In Weaver, you can create application pages by directly arranging basic
> application elements, HTML containers, form fields, buttons and other tools on
> the screen.
### Visual page designer {#visual-page-designer}
> Tools for creating application pages in Weaver, including interface designer
> and "Logicor" page code generator.
### Contract editor {#contract-editor}
> A tool for creating contracts using visual pages in Weaver.
### Multilingual resources {#multilingual-resources}
> The module of application page localization in Weaver, which associates the
> label on the application page with the text value of the selected language.
### Application export {#application-export}
> Save the source code of all tables, pages, and contracts of the application as
> files.
### Application import {#application-import}
> Load all tables, pages, and contracts of an application included in the export
> file into the ECOLIB.
### Smart law {#smart-law}
> It is a special set of smart contracts that contain regulatory information and
> used to manage and control the operation and register access rights.
### Legal system {#legal-system}
> A set of rules and mechanisms established in smart law, which can regulate the
> relationship between ECOLIB users, define procedural rules for changing
> protocol parameters, and define various challenging solutions.
### Application {#application}
> Create fully functional software products in Weaver's IDE.
>
> An application is a collection of elements such as database tables, smart
> contracts, and user pages with configuration access rights.
### Page {#page}
> The program code written in the Logicor template language that forms an
> interactive interface on the screen.
### Code segment {#code-segment}
> The program code written in the Logicor template language that can be reused
> in application pages.
### Access rights {#access-rights}
> Conditions to get access rights for creating and editing tables, contracts and
> pages.
>
> The access rights to tables can be configured with rights to add rows and
> columns, and edit the values in columns.
### Honor node {#honor-node}
> A node in the network node that has the right to generate and verify blocks.
### Guardian node {#guardian-node}
> A node on the network used to store the latest version of the complete
> blockchain.
### Concurrent transaction processing {#concurrent-transaction-processing}
> A method to increase transaction processing speed by processing data from
> different ECOLIBs at the same time.
---
## File: docs/reference/api2.md
# RESTful API v2
Weaver All functions provided, including authentication, ecosystem data
reception, error handling, database table manipulation, page and contract
execution are available through IBAX Blockchain Platform's REST API is
available.
By using the REST API, developers can access any of the platform's features
without using Weaver.
API command calls are executed by addressing `/api/v2/command/[param]`, where
`command` is the command name and `param` is the additional parameter. The
request parameters must be specified using the
`Content-Type: x-www-form-urlencoded` The format is sent. The server response
result is in JSON format.
## Error response handling {#error-response-handling}
Return status in case of successful request execution `200`. If an error occurs,
in addition to the error status, a JSON object with the following fields will be
returned.
- **error**
> Error identifier.
- **msg**
> Error text message.
- **params**
> An array of additional parameters that can be placed in the error message.
**Response Example**
```json
400 (Bad request)
Content-Type: application/json
{
"err": "E_INVALIDWALLET",
"msg": "Wallet 1234-5678-9012-3444-3488 is not valid",
"params": ["1234-5678-9012-3444-3488"]
}
```
### Error list {#error-list}
> `E_CONTRACT`
No `%s` contract exists
> `E_DBNIL`
Database is empty
> `E_DELETEDKEY`
Account address is frozen
> `E_ECOSYSTEM`
Ecosystem `%d` does not exist
> `E_EMPTYPUBLIC`
Invalid account public key
> `E_KEYNOTFOUND`
Account address not found
> `E_HASHWRONG`
Incorrect hash
> `E_HASHNOTFOUND`
Hash not found
> `E_HEAVYPAGE`
Too much page loading
> `E_INVALIDWALLET`
Wallet address `%s` Invalid
> `E_LIMITTXSIZE`
The transaction size has exceeded the limit
> `E_NOTFOUND`
Page or menu content not found
> `E_PARAMNOTFOUND`
Parameters not found
> `E_PERMISSION`
No permission
> `E_QUERY`
Database query error
> `E_RECOVERED`
API panic error occurs.
If a panic error occurs, an error is returned.
This error means that you have encountered a bug that needs to be found and fixed.
> `E_SERVER`
Server error.
Return if there is an error in the golang library function. The \*msg\* field contains the error text message.
**E_SERVER** may appear in response to any command Error.
If it occurs due to an incorrect input parameter, it can be changed to a related error. In another case, this error reports an invalid operation or incorrect system configuration, which requires a more detailed investigation report.
> `E_SIGNATURE`
Incorrect signature
> `E_STATELOGIN`
`%s` is not a member of the ecosystem `%s`
> `E_TABLENOTFOUND`
Data sheet `%s` not found
> `E_TOKENEXPIRED`
The session has expired `%s`
> `E_UNAUTHORIZED`
Unauthorized.
In case no login is performed or the session expires, except for `getuid, login` Any command other than **E_UNAUTHORIZED** returns an error.
> `E_UNKNOWNUID`
Unknown UID
> `E_UPDATING`
Nodes are updating the blockchain
> `E_STOPPING`
Node is stopped
> `E_NOTIMPLEMENTED`
Not yet achieved
> `E_BANNED`
This account address is prohibited in `%s`
> `E_CHECKROLE`
Access denied
CLB Unavailable Interface
---
> Interface requests for which the CLB node is not available.
- metrics
- txinfo
- txinfoMultiple
- appparam
- appparams
- appcontent
- history
- balance
- block
- maxblockid
- blocks
- detailed_blocks
- ecosystemparams
- systemparams
- ecosystems
- ecosystemparam
- ecosystemname
- walletHistory
- tx_record
## Request Type {#request-type}
**Uniform use**
- application/x-www-form-urlencoded
## Authentication Interface {#authentication-interface}
[JWT token](https://jwt.io) Used for authentication. The JWT token must be
placed in each request header after it is received:
`Authorization: Bearer TOKEN_HERE`.
### getuid {#getuid}
**GET**/ returns a unique value, signs it with the private key, and then uses.
The [login](#login) command sends it back to the server.
Generate a temporary JWT token that needs to be passed to **Authorization** when
calling **login**.
**Request**
```text
GET
/api/v2/getuid
```
**Response**
- `uid`
> Signature number.
- `token`
> The temporary token passed during login.
>
> The life cycle of a temporary token is 5 seconds.
- `network_id`
> Server identifier.
- `cryptoer`
> Elliptic curve algorithm.
- `hasher`
> hash algorithm.
**Response Example 1**
````json
200 (OK)
Content-Type: application/json
```json
{
"uid": "4999317241855959593",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9........I7LY6XX4IP12En6nr8UPklE9U4qicqg3K9KEzGq_8zE",
"network_id": "4717243765193692211"
}
````
In the case that no authorization is required (the request contains
**Authorization**), the following message will be returned:
- `expire`
> Expiration time.
- `ecosystem`
> Ecosystem ID.
- `key_id`
> Account address.
- `address`
> Wallet address `XXXX-XXXX-..... -XXXX`.
- `network_id`
> Server identifier.
**Response Example 2**
```json
200 (OK)
Content-Type: application/json
{
"expire": "2159h59m49.4310543s",
"ecosystem_id": "1",
"key_id": "-654321",
"address": "1196-...... -3496",
"network_id": "1"
}
```
**Error Response**
_E_SERVER_
### login {#login}
**POST**/ User authentication.
> **getuid** should be called first command in order to receive the unique value
> and sign it. getuid's temporary JWT token needs to be passed in the request
> header.
>
> If the request is successful, the token received in the response is contained
> in **Authorization**.
**Request**
```text
POST
/api/v2/login
```
- `ecosystem`
> Ecosystem ID.
>
> If not specified, defaults to the first ecosystem ID.
- `expire`
> Lifecycle of the JWT token, in seconds, default is 28800.
- `pubkey`
> Hexadecimal account public key.
- `key_id`
> Account address `XXXX-... -XXXX`.
>
> Use this parameter if the public key is already stored in the blockchain. It
> cannot be used with _pubkey_ parameters are used together.
- `signature`
> The uid signature received via getuid.
**Response**
- `token`
> JWT token.
- `ecosystem_id`
> Ecosystem ID.
- `key_id`
> Account Address ID
- `account`
> Wallet address `XXXX-XXXX-..... -XXXX`.
- `notify_key`
> Notification ID.
- `isnode`
> Whether the account address is the owner of the node. Values: `true,false`.
- `isowner`
> Whether the account address is the creator of the ecosystem. Values:
> `true,false`.
- `clb`
> Whether the logged-in ecosystem is CLB. Values: `true,false`.
- `roles` [Omitempty](#omitempty)
> Role list: `[{Role ID,Role Name}]`.
**Response Example**
```json
200 (OK)
Content-Type: application/json
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.....30l665h3v7lH85rs5jgk0",
"ecosystem_id": "1",
"key_id": "-54321",
"account": "1285-... -7743-4282",
"notify_key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..... _JTFfheD0K4CfMbvVNpOJVMNDPx25zIDGir9g3ZZM0w",
"timestamp": "1451309883",
"roles": [
{
"role_id": 1,
"role_name": "Developer"
}
]
}
```
**Error Response**
_E_SERVER, E_UNKNOWNUID, E_SIGNATURE, E_STATELOGIN, E_EMPTYPUBLIC_
## Server Side command interface {#server-side-command-interface}
### version {#version}
**GET**/ Returns the current server version.
This request does not require login authorization.
**Request**
```text
GET
/api/v2/version
```
**Response Example**
```json
200 (OK)
Content-Type: application/json
"1.3.0 branch.main commit.790..757 time.2021-08-23-08:20:19(UTC)"
```
## Data Request Function Interface {#data-request-function-interface}
### balance {#balance}
**GET**/ Requests the balance of the account address in the current ecosystem.
This request does not require login authorization.
**Request**
```text
GET
/api/v2/balance/{wallet}
```
- `wallet`
> Address identifier, can be specified in any format
> `int64, uint64, XXXX-... -XXXX`. Look up the address in the ecosystem where
> the user is currently logged in.
- `ecosystem` [Omitempty](#omitempty) Default ecosystem 1
> Ecosystem id.
**Response**
- `amount`
> The minimum unit of contract account balance.
- `money`
> Account balance.
- `total`
> Account balance.
- `utxo`
> UTXO account balance.
- _digits_
> precision.
**Response Example**
```json
200 (OK)
Content-Type: application/json
{
"amount": "877450000000000",
"money": "877.45",
"total": "877450000000000",
"digits": 6,
"utxo": "0"
}
```
**Error Response**
_E_SERVER, E_INVALIDWALLET_
### blocks {#blocks}
**GET**/ Returns a list containing additional information related to the
transactions in each block.
This request does not require login authorization.
**Request**
```text
GET
/api/v2/blocks
```
- `block_id` [Omitempty](#omitempty) Default is 0
> The height of the starting block to query.
- `count` [Omitempty](#omitempty) (default is 25, max request 1000)
> Number of blocks.
**Response**
- `Block height`: List of transactions in the block and additional information
for each transaction.
- `hash`: Trading Hash.
- `contract_name`: Contract name.
- `params`: Array of contract parameters.
- `key_id`:
- For the first block, it is the account address of the first block that
signed the transaction.
- For all other blocks, is the address of the account that signed the
transaction.
**Response Example**
```json
200 (OK)
Content-Type: application/json
{ "1":
[{"hash": "O1LhrjKznrYa0z5n5cej6p5Y1j5E9v/oV27VPRJmfgo=",
"contract_name":"",
"params":null,
"key_id":-118432674655542910}]
}
```
**Error Response**
_E_SERVER, E_NOTFOUND_
### detailed_blocks {#detailed-blocks}
**GET**/ Returns a list containing detailed additional information about the
transactions in each block.
This request does not require login authorization.
**Request**
```text
GET
/api/v2/detailed_blocks
```
- `block_id` [Omitempty](#omitempty) Default is 0
> The height of the starting block to query.
- `count` [Omitempty](#omitempty) (default is 25, max request 1000)
> Number of blocks.
**Response**
- `Block height` The block height.
- `blockhead` The block header contains the following fields.
- `block_id` Block height.
- `time` Block generation timestamp.
- `key_id` Sign the account address for the block.
- `node_position` The location of the node that generated the block in the
honor node list.
- `version` Block structure version.
- `hash` Block Hashing.
- `node_position` the location of the node that generated the block in the
honor node list.
- `key_id` The address of the account that signed the block.
- `time` Block generation timestamp.
- `tx_count` Number of transactions within the block.
- `size` The block size.
- `rollback_hash` Block rollback hash.
- `merkle_root` The block deals with the Merkle tree.
- `bin_data` Serialization of the block header, all transactions within the
block, the previous block hash, and the private key of the node that
generated the block.
- `transactions` List of transactions in the block and additional information
about each transaction.
- `hash` Trading hash.
- `contract_name` Contract name.
- `params` Contract parameters.
- `key_id` Sign the account address for this transaction.
- `time` Transaction generation timestamp.
- `type` Transaction type.
- `size` Trade Size.
**Response Example**
```json
200 (OK)
Content-Type: application/json
{"1":
{"header":
{"block_id":1,
"time":1551069320,
"ecosystem_id":0,
"key_id":-118432674655542910,
"node_position":0,
"version":1},
"hash":"3NxhvswmpGvRdw8HdkrniI5Mx/q14Z4d5hwGKMp6KHI=",
"ecosystem_id":0,
"node_position":0,
"key_id":-118432674655542910,
"time":1551069320,
"tx_count":1,
"size": "1.69KiB",
"rollbacks_hash":"I2JHugpbdMNxBdNW1Uc0XnbiXFtzB74yD9AK5YI5i/k=",
"mrkl_root":"MTZiMjY2NGJjOWY3MDAyODlhYjkyMDVhZDQwNDgxNzkxMjY1MWJjNjczNDkyZjk5MWI2Y2JkMjAxNTIwYjUyYg==",
"bin_data":null,
"sys_update":false,
"gen_block":false,
"stop_count":0,
"transactions":[
{
"hash":"O1LhrjKznrYa0z5n5cej6p5Y1j5E9v/oV27VPRJmfgo=",
"contract_name":"",
"params":null,
"key_id":0,
"time":0,
"type":0,
"size": "300.00B"
}
]}
}
```
**Error Response**
_E_SERVER, E_NOTFOUND_
### `/data/{id}/data/{hash}` {#data-id-data-hash}
**GET**/ If the specified hash matching the data in the binary watch, field, and
records, this request will return the data. Otherwise, return error.
The request does not require login authorization.
**Request**
```text
GET
/data/{id}/data/{hash}
```
- `id`
> Record ID.
- `hash`
> Hash request data.
**Response**
> Binary data
**Response Example**
```json
200 (OK)
Content-Type: *
{
"name": "NFT Miner",
"conditions": "ContractConditions(\"@1DeveloperCondition\")",
"data": [
{
"Type": "contracts",
"Name": "NewNFTMiner",
},
...
]
}
```
**Error Response**
_E_SERVER, E_NOTFOUND, E_HASHWRONG_
### `/data/{table}/id/{column}/{hash}`{#data-table-id-column-hash}
**GET**/ If the specified hash matches the data in the specified table, field,
and records, the request will return the data. Otherwise, return error.
The request does not require login authorization.
**Request**
```text
GET
/data/{table}/id/{column}/{hash}
```
- `table`
> Data table name.
- `id`
> Record ID.
- `column`
> Data table name, only one
- `hash`
> Hash request data.
**Response**
> Binary data
**Response Example**
```json
200 (OK)
Content-Type: application/octet-stream
Content-Disposition: attachment
SetVar(this_page, @1voting_list).(this_table, @1votings)
Include(@1pager_header)
SetTitle("$@1voting_list$")
Span(Class: text-muted h5 m0 mb ml-lg, Body: Span(Class: ml-sm, Body: "$@1votings_list_desc$"))
AddToolButton(Title: $@1templates_list$, Page: @1voting_templates_list, Icon: icon-pin)
AddToolButton(Title: $@1create$, Page: @1voting_create, Icon: icon-plus).Popup(60, $@1new_voting$)
```
**Error Response**
_E_SERVER, E_NOTFOUND, E_HASHWRONG_
### keyinfo {#keyinfo}
**GET**/ Return to a list of ecosystems, which contains the role of registered
the specified address.
The request does not require login authorization.
**Request**
```text
GET
/api/v2/keyinfo/{address}
```
- `address`
> Address identifier, you can specify `int64, uint64, xxxx -...-xxxx`.
>
> This request is query in all ecosystems.
**Response**
- `ecosystem`
> Ecosystem ID.
- `name`
> Ecosystem name.
- `roles`
> Activities with _id_ and _name_ fields.
**Response Example**
```json
200 (OK)
Content-Type: application/json
[{
"ecosystem":"1",
"name":"platform ecosystem",
"roles":[{"id":"1","name":"Governancer"},{"id":"2","name":"Developer"}]
}]
```
**Error Response**
_E_SERVER, E_INVALIDWALLET_
### walletHistory {#wallethistory}
**GET**/ Return to the current account transaction history record, find it
according to the ID of the ID.
[Authorization](#authorization)
**Request**
- `searchType`
> Find Type (Income: Turn into Outcom: Turn out all: All, default).
- `page` [Omitempty](#omitempty)
> Find the number of pages, the first page default, min: 1
- `limit` [Omitempty](#omitempty)
> Credit number, default 20 articles. min: 1, MAX: 500
```text
GET
/api/v2/walletHistory?searchType=all&page=1&limit=10
```
**Response**
- `total`
> Total number of entries.
- `page`
> Number of current page.
- `limit`
> Currently find the number of bars.
- `list` Each element in the array contains the following parameters:
- `id` Stripe ID.
- `sender_id` Send key_id
- `sender_add` Send the account address
- `recipient_id` Accept key_id
- `recipient_add` Accept the account address
- `amount` Transaction amount
- `comment` Trading remarks
- `block_id` Block height
- `tx_hash` Trading hash
- `created_at` Transaction creation time, millisecond time stamp
- `money` Transaction amount
**Response Example**
```json
200 (OK)
Content-Type: application/json
{
"page": 1,
"limit": 10,
"total": 617,
"list": [
{
"id": 650,
"sender_id": 666081971617879...,
"sender_add": "0666-0819-7161-xxxx-5186",
"recipient_id": 666081971617879...,
"recipient_add": "0666-0819-7161-xxxx-5186",
"amount": "242250000",
"comment": "taxes for execution of @1Export contract",
"block_id": 209,
"tx_hash": "a213bc767d710a223856d83515d53518075b56fb9e9c063bce8a256c20ff0775",
"created_at": 1666001092090,
"money": "0.00024225"
}
...
]
}
```
**Error Response**
_E_SERVER_
### `listWhere/{name}` {#listwhere-name}
**GET**/ Return to the entry of the data table specified in the current
ecosystem. You can specify columns to be returned.
[Authorization](#authorization)
**Request**
- `name`
> Data table name.
- `limit` [Omitempty](#omitempty)
> Credit number, default 25.
- `offset` [Omitempty](#omitempty)
> Disposal, default to 0.
- `order` [Omitempty](#omitempty)
> Sorting method, default `id ASC`.
- `columns` [Omitempty](#omitempty)
> The list of request columns is separated by commas. If it is not specified,
> all columns will be returned. In all cases, the `id` column will be
> returned.
- `where` [Omitempty](#omitempty)
> Query condition
>
> Example: If you want to query `id > 2 and name = john`
>
> You can use: where: `{"id": {"$ gt": 2}, "name": {"$eq": "john"}}`.
>
> For details, please refer to [DBFind](../ topics/script.md#dbfind) where
> syntax
```text
POST
/api/v2/listWhere/mytable
```
**Response**
- `count`
> Total number of entries.
- `list`
> Each element in the array contains the following parameters:
- `id`
> Stripe ID.
- `...`
> Data tables other columns
**Response Example**
```json
200 (OK)
Content-Type: application/json
{
"count": 1,
"list": [
{
"account": "xxxx-0819-7161-xxxx-xxxx",
"ecosystem": "1",
"id": "12",
"key": "avatar",
"value": "{\"binary_id\": 4}"
}
]
}
```
**Error Response**
_E_SERVER_,_E_TABLENOTFOUND_
### `nodelistWhere/{name}` {#nodelistwhere-name}
**GET**/ Return to the specified data table. You can specify columns to be
returned. The type in the data table is **BYTEA** Do hexadecimal encoding
processing
[Authorization](#authorization)
**Request**
- `name`
> Data table name.
- `limit` [Omitempty](#omitempty)
> Credit number, default 25.
- `offset` [Omitempty](#omitempty)
> Disposal, default to 0.
- `order` [Omitempty](#omitempty)
> Sorting method, default `id ASC`.
- `columns` [Omitempty](#omitempty)
> The list of request columns is separated by commas. If it is not specified,
> all columns will be returned. In all cases, the `id` column will be
> returned.
- `where` [Omitempty](#omitempty)
> Query condition
>
> Example: If you want to query `id > 2 and name = john`
>
> You can use: where: `{"id": {"$ gt": 2}, "name": {"$eq": "john"}}`.
>
> For details, please refer to [DBFind](../ topics/script.md#dbfind) where
> syntax
```text
GET
/api/v2/nodelistWhere/mytable
```
**Response**
- `count`
> Total number of entries.
- `list`
> Each element in the array contains the following parameters:
- `id`
> Stripe ID.
- `...`
> Data tables other columns
**Response Example**
```json
200 (OK)
Content-Type: application/json
{
"count": 1,
"list": [
{
"account": "xxxx-0819-7161-xxxx-xxxx",
"ecosystem": "1",
"id": "12",
"key": "avatar",
"value": "{\"binary_id\": 4}"
}
]
}
```
**Error Response**
_E_SERVER_,_E_TABLENOTFOUND_
## Get Metrics Interface {#get-metrics-interface}
### metrics/keys {#metrics-keys}
**GET**/ Returns the number of ecosystem 1 account addresses.
**Request**
```text
GET
/api/v2/metrics/keys
```
**Response Example**
```json
200 (OK)
Content-Type: application/json
{
"count": 28
}
```
### metrics/blocks {#metrics-blocks}
**GET**/ Returns the number of blocks.
**Request**
```text
GET
/api/v2/metrics/blocks
```
**Response Example**
```json
200 (OK)
Content-Type: application/json
{
"count": 28
}
```
### metrics/transactions {#metrics-transactions}
**GET**/ Returns the total number of transactions.
**Request**
```text
GET
/api/v2/metrics/transactions
```
**Response Example**
```json
200 (OK)
Content-Type: application/json
{
"count": 28
}
```
### metrics/ecosystems {#metrics-ecosystems}
**GET**/ Returns the number of ecosystems.
**Request**
```text
GET
/api/v2/metrics/ecosystems
```
**Response Example**
```json
200 (OK)
Content-Type: application/json
{
"count": 28
}
```
### metrics/honornodes {#metrics-honornodes}
**GET**/ Returns the number of honor nodes.
This request does not require login authorization.
```
GET
/api/v2/metrics/honornodes
```
**Response Example**
```json
200 (OK)
Content-Type: application/json
{
"count": 28
}
```
## Ecosystem Interface {#ecosystem-interface}
### ecosystemname {#ecosystemname}
**GET**/ Returns the name of the ecosystem by its identifier.
This request does not require login authorization.
```text
GET
/api/v2/ecosystemname?id=1
```
- _id_
> Ecosystem ID.
**Response Example**
```json
200 (OK)
Content-Type: application/json
{
"ecosystem_name": "platform_ecosystem"
}
```
**Error Response**
_E_PARAMNOTFOUND_
### `appparams/{appid}` {#appparams-appid}
[Authorization](#authorization)
**GET**/ Returns a list of application parameters in the current or specified
ecosystem.
**Request**
```text
GET
/api/v2/appparams/{appid}
```
- `appid`
> Application ID.
- `ecosystem`
> Ecosystem ID; if not specified, the current ecosystem parameter will be
> returned.
- `names`
> The list of received parameters.
>
> You can specify a comma-separated list of parameter names, for example:
> `/api/v2/appparams/1?names=name,mypar`.
**Response**
- `list`
> Each element of the array contains the following parameters.
>
> - `name`, the name of the parameter.
> - `value`, the value of the parameter.
> - `conditions`, change the permissions of the parameters.
**Response Example**
```json
200 (OK)
Content-Type: application/json
{
"list": [{
"name": "name",
"value": "MyState",
"conditions": "true",
},
{
"name": "mypar",
"value": "My value",
"conditions": "true",
},
]
}
```
**Error Response**
_E_ECOSYSTEM_
### `appparam/{appid}/{name}` {#appparam-appid-name}
[Authorization](#authorization)
**GET**/ Returns information about the parameter **`{name}`** of the application
**`{appid}`** in the current or specified ecosystem.
**Request**
```text
GET
/api/v2/appparam/{appid}/{name}[?ecosystem=1]
```
- `appid`
> Application ID.
- `name`
> The name of the requested parameter.
- `ecosystem` [Omitempty](#omitempty)
> Ecosystem ID (optional parameter).
>
> Returns the current ecosystem by default.
**Response**
- `id`
> Parameter ID.
- `name`
> Parameter name.
- `value`
> The parameter value.
- `conditions`
> Permission to change parameters.
**Response Example**
```json
200 (OK)
Content-Type: application/json
{
"id": "10",
"name": "par",
"value": "My value",
"conditions": "true"
}
```
**Error Response**
_E_ECOSYSTEM, E_PARAMNOTFOUND_
### ecosystemparams {#ecosystemparams}
[Authorization](#authorization)
**GET**/ Returns a list of ecosystem parameters.
**Request**
```text
GET
/api/v2/ecosystemparams/[?ecosystem=... &names=...]
```
- `ecosystem` [Omitempty](#omitempty)
> Ecosystem ID. if not specified, the current ecosystem ID will be returned.
- `names` [Omitempty](#omitempty)
> List of request parameters, separated by commas.
>
> For example: `/api/v2/ecosystemparams/?names=name,currency,logo`.
**Response**
- `list`
> Each element of the array contains the following parameters.
>
> - `name`
>
> > Parameter name.
>
> - `value`
>
> > Parameter value.
>
> - `conditions`
>
> > Change permissions for parameters.
**Response Example**
```json
200 (OK)
Content-Type: application/json
{
"list": [{
"name": "name",
"value": "MyState",
"conditions": "true",
},
{
"name": "currency",
"value": "MY",
"conditions": "true",
},
]
}
```
**Error Response**
_E_ECOSYSTEM_
### `ecosystemparam/{name}` {#ecosystemparam-name}
[Authorization](#authorization)
**GET**/ Returns information about the parameter **`{name}`** in the current or
specified ecosystem.
**Request**
```text
GET
/api/v2/ecosystemparam/{name}[?ecosystem=1]
```
- `name`
> The name of the requested parameter.
- `ecosystem` [Omitempty](#omitempty)
> The default is to return the current ecosystem ID.
**Response**
- `name`
> Parameter name.
- `value`
> The parameter value.
- `conditions`
> Permission to change parameters.
**Response Example**
```json
200 (OK)
Content-Type: application/json
{
"name": "currency",
"value": "MYCUR",
"conditions": "true"
}
```
**Error Response**
_E_ECOSYSTEM_
### `tables/[?limit=... &offset=... ]` {#tables-limit-offset}
[Authorization](#authorization)
**GET**/ Returns a list of data tables for the current ecosystem. You can set
the offset and the number of entries.
**Request**
- `limit` [Omitempty](#omitempty)
> Number of entries, default 100, maximum 1000.
- `offset` [Omitempty](#omitempty)
> Offset, default is 0.
```text
GET
/api/v2/tables?limit=... &offset=...
```
**Response**
- `count`
> The total number of entries in the data table.
- `list`
> Each element of the array contains the following parameters.
>
> > - `name`
> >
> > > Data table name without prefix.
> >
> > - `count`
> >
> > > The number of entries in the data table.
**Response Example**
```json
200 (OK)
Content-Type: application/json
{
"count": "100"
"list": [{
"name": "accounts",
"count": "10",
},
{
"name": "citizens",
"count": "5",
},
]
}
```
### `table/{name}` {#table-name}
[Authorization](#authorization)
**GET**/ Returns information about the current ecosystem request data table.
**Request**
- `name`
> Data table name.
```text
GET
/api/v2/table/{table_name}
```
Returns the following field information.
- `name`
> Data table name.
- `insert`
> Permission to add new entries.
- `new_column`
> Add field permissions.
- `update`
> Change entry permissions.
- `columns`
> Array of field-related information.
>
> > - `name`
> >
> > > Field name.
> >
> > - `type`
> >
> > > Field data type.
> >
> > - `perm`
> >
> > > Change the permissions for the field value.
### `list/{name}[?limit=... &offset=... &columns=... ]` {#list-name-limit-offset-columns}
[Authorization](#authorization)
**GET**/ Returns a list of the specified data table entries in the current
ecosystem. You can set the offset and the number of entries.
**Request**
- `name`
> Data table name.
- `limit` [Omitempty](#omitempty)
> Number of entries, default 25 entries.
- `offset` [Omitempty](#omitempty)
> Offset, default is 0.
- `columns` [Omitempty](#omitempty)
> A comma-separated list of requested columns, if not specified, all columns
> will be returned. The id column will be returned in all cases.
```text
GET
/api/v2/list/mytable?columns=name
```
**Response**
- `count`
> Total number of entries.
- `list`
> Each element of the array contains the following parameters.
>
> > - `id`
> >
> > > Entry ID.
> >
> > - The sequence of request columns.
**Response Example**
```json
200 (OK)
Content-Type: application/json
{
"count": "10"
"list": [{
"id": "1",
"name": "John",
},
{
"id": "2",
"name": "Mark",
},
]
}
```
### `sections[?limit=... &offset=... &lang=]` {#sections-limit-offset-lang}
[Authorization](#authorization)
**GET**/ Returns a list of entries in the _sections_ table of the current
ecosystem, with the ability to set an offset and number of entries.
If the _role_access_ field contains a list of roles and does not include the
current role, no records will be returned. The data in the _title_ field will be
replaced with the language resource specified in the request header
_Accept-Language_.
**Request**
- `limit` [Omitempty](#omitempty)
> Number of entries, default 25 entries.
- `offset` [Omitempty](#omitempty)
> Offset, default is 0.
- `lang` [Omitempty](#omitempty)
> This field specifies the multilingual resource code or localization, e.g.,
> _en, de_. If the specified language resource is not found, e.g., _en-US_, it
> will search within the language resource group _en_.
```text
GET
/api/v2/sections
```
**Response**
- `count`
> _sections_ Total number of table entries.
- `list`
> Each element of the array contains information about all columns in the
> actions table.
**Response Example**
```json
200 (OK)
Content-Type: application/json
{
"count": "2"
"list": [{
"id": "1",
"title": "Development",
"urlpage": "develop",
...
},
]
}
```
**Error Response**
_E_TABLENOTFOUND_
### `row/{name}/{id}[?columns=]` {#row-name-id-columns}
[Authorization](#authorization)
**GET**/ Returns the entry for the specified data table in the current
ecosystem. You can specify the columns to be returned.
**Request**
- `name`
> Data table name.
- `id`
> Entry ID.
- `columns` [Omitempty](#omitempty)
> A comma-separated list of requested columns, if not specified, all columns
> will be returned. The id column will be returned in all cases.
```text
GET
/api/v2/row/mytable/10?columns=name
```
**Response**
- `value`
> Array of received column values
>
> > - `id`
> >
> > > Entry ID.
> >
> > - The sequence of request columns.
**Response Example**
```json
200 (OK)
Content-Type: application/json
{
"values": {
"id": "10",
"name": "John",
}
}
```
**Error Response**
_E_NOTFOUND_
### `row/{name}/{column}/{id}` {#row-name-colorn-id}
[Authorization] (#authorization)
**GET**/ Return to the entry of the data table specified in the current
ecosystem. You can specify columns to be returned.
**Request**
- `Name`
> Data table name.
- `colorn`
> Data list name.
- `ID`
> Stripe ID.
- `columns` [omitempty] (#omitempty)
> The list of request lists is separated by commas. If it is not specified,
> all columns will be returned. In all cases, the ID column will be returned.
```text
GET
/api/v2/row/mytable/name/John?columns=name
```
**Response**
- `value`
> Array of receiving column values Forecast
>
> - `ID`
> > > Strip ID.
> - -The sequence of the request column.
**Response Example**
```json
200 (OK)
Content-Type: application/json
{
"values": {
"id": "10",
"name": "John",
}
}
```
**Error Response**
_E_NOTFOUND_
### systemparams {#systemparams}
[Authorization](#authorization)
**GET**/ Returns a list of platform parameters.
**Request**
```text
GET
/api/v2/systemparams/[?names=...]
```
- `names` [Omitempty](#omitempty)
A list of request parameters, separated by commas. For example
`/api/v2/systemparams/?names=max_columns,max_indexes`.
**Response**
- `list`
> Each element of the array contains the following parameters.
>
> > - `name`
> >
> > > Parameter name.
> >
> > - `value`
> >
> > > Parameter values.
> >
> > - `conditions`
> >
> > > Change the permission of the parameter.
**Response Example**
```json
200 (OK)
Content-Type: application/json
{
"list": [{
"name": "max_columns",
"value": "100",
"conditions": "ContractAccess("@1UpdateSysParam")",
},
{
"name": "max_indexes",
"value": "1",
"conditions": "ContractAccess("@1UpdateSysParam")",
},
]
}
```
**Error Response**
_E_PARAMNOTFOUND_
### `history/{name}/{id}` {#history-name-id}
[Authorization](#authorization)
**GET**/ Returns the change record for the entry in the specified data table in
the current ecosystem.
**Request**
```text
GET
/api/v2/history?name=contracts&id=5
```
> - `name`
>
> Data Table Name.
>
> - `id`
>
> > Entry ID.
**Response**
> - `list`
>
> Each element of the array contains a change record for the requested entry.
**Response Example**
```json
200 (OK)
Content-Type: application/json
{
"list": [
{
"name": "default_page",
"value": "P(class, Default Ecosystem Page)"
},
{
"menu": "default_menu"
}
]
}
```
### `interface/{page|menu|snippet}/{name}` {#interface-page-menu-snippet-name}
[Authorization](#authorization)
**GET**/ Returns the entry for the _name_ field in the specified data table
(pages, menu or snippet) for the current ecosystem.
```text
GET
/api/v2/interface/page/default_page
/api/v2/interface/menu/default_menu
/api/v2/interface/snippet/welcome
```
**Request**
- `name`
> Specifies the name of the entry in the table.
**Response**
- `id`
> Entry ID.
- `name`
> Entry name.
- `other`
> Other columns of the table.
**Response Example**
```json
200 (OK)
Content-Type: application/json
{
"id": "1",
"name": "default_page",
"value": "P(Page content)",
"default_menu": "default_menu",
"validate_count": 1
}
```
**Error Response**
_E_QUERY_, _E_NOTFOUND_
## Contract Function Interface {#contract-function-interface}
### `contracts[?limit=... &offset=... ]` {#contracts-limit-offset}
[Authorization](#authorization)
**GET**/ Returns a list of contracts in the current ecosystem, with the ability
to set offsets and the number of entries.
**Request**
- `limit` [Omitempty](#omitempty)
> Number of entries, default 25 entries.
- `offset` [Omitempty](#omitempty)
> Offset, default is 0.
```text
GET
/api/v2/contracts
```
**Response**
- `count`
> Total number of entries.
- `list`
> Each element of the array contains the following parameters.
>
> > - `id`
> >
> > > Contract ID.
> >
> > - `name`
> >
> > > Contract name.
> >
> > - `value`
> >
> > > Contract contents.
> >
> > - `wallet_id`
> >
> > > The account address to which the contract is tied.
> >
> > - `address`
> >
> > > Contract-bound wallet address `XXXX-... -XXXX`.
> >
> > - `ecosystem_id`
> >
> > > The ecosystem ID to which the contract belongs.
> >
> > - `app_id`
> >
> > > The application ID to which the contract belongs.
> >
> > - `conditions`
> >
> > > Change the permission of the contract.
> >
> > - `token_id`
> >
> > > The ID of the ecosystem where the pass is used to pay the contract fee.
**Response Example**
```json
200 (OK)
Content-Type: application/json
{
"count": "10"
"list": [{
"id": "1",
"name": "MainCondition",
"token_id": "1",
"wallet_id": "0",
"value": "contract MainCondition {
conditions {
if(EcosysParam(`founder_account`)!=$key_id)
{
warning `Sorry, you dont have access to this action.`
}
}
}",
"address":"0000-0000-0000-0000-0000",
"conditions":"ContractConditions(`MainCondition`)"
},
...
]
}
```
### `contract/{name}` {#contract-name}
[Authorization](#authorization)
**GET**/ Returns information about the specified contract. The default is to
query the contract in the current ecosystem.
**Request**
- `name`
> Contract name.
```text
GET
/api/v2/contract/mycontract
```
**Response**
- `id`
> Contract ID in VM.
- `name`
> Contract name with ecosystem ID `@1MainCondition`.
- `state`
> The ecosystem ID of the contract.
- `walletid`
> The address of the account to which the contract is tied.
- `tokenid`
> The ecosystem ID of the pass that is used to pay for the contract.
- `address`
> Contract-bound wallet address `XXXX-... -XXXX`.
- `tableid`
ID of the entry in the > _contracts_ table where the contract is located.
- `fields`
> The array contains structural information for each parameter of the contract
> **data** section.
>
> > - `name`
> >
> > > Parameter name.
> >
> > - `type`
> >
> > Parameter type.
> >
> > - `optional`
> >
> > > Parameter options, \`true\` means optional parameters, \`false\` means
> > > mandatory parameters.
**Response Example**
```json
200 (OK)
Content-Type: application/json
{
"fields" : [
{"name": "amount", "type": "int", "optional": false},
{"name": "name", "type": "string", "optional": true}
],
"id": 150,
"name":"@1mycontract",
"tableid" : 10,
}
```
**Error Response**
_E_CONTRACT_
### sendTX {#sendtx}
[Authorization](#authorization)
**POST**/ Receives the transactions in the parameters and adds them to the
transaction queue, returning a transaction hash if the request is executed
successfully. This hash yields the corresponding transaction within the block
and is included in the error text message in case of an Error Response.
**Request**
- `tx_key`
> Transaction content, this parameter can specify any name and supports
> receiving multiple transactions.
```text
POST
/api/v2/sendTx
Headers:
Content-Type: multipart/form-data
Parameters:
tx1 - Transaction 1
txN - Trading N
```
**Response**
- `hashes`
> Transaction hash arrays.
>
> > - `tx1`
> >
> > > Trading 1 hash.
> >
> > - `txN`
> >
> > > Trading N's hash.
**Response Example**
```json
200 (OK)
Content-Type: application/json
{
"hashes": {
"tx1": "67afbc435634..... ",
"txN": "89ce4498eaf7..... ",
}
```
**Error Response**
_E_LIMITTXSIZE_,_E_BANNED_
### txstatus {#txstatus}
[Authorization](#authorization)
**POST**/ Returns the block ID and error message for the specified transaction
hash. If the return values for the block ID and error text message are null,
then the transaction is not yet contained in the block.
**Request**
- `data`
> JSON list of transaction hashes.
```text
{"hashes":["contract1hash", "contract2hash", "contract3hash"]}
```
```text
POST
/api/v2/txstatus/
```
**Response**
- `results`
> The transaction hash is used as the key and the transaction detail is used
> as the value in the data dictionary.
>
> `hash`
>
> > Trading Hash.
> >
> > - `blockid`
> >
> > > If the transaction is executed successfully, the block ID will be
> > > returned. If the transaction fails, the _blockid_ will be
> > > `[0]{.title-ref}`.
> >
> > - `result`
> >
> > > Returns the result of the transaction via the **\$result** variable.
> >
> > - `errmsg`
> >
> > > Returns an error text message if the execution of the transaction
> > > fails.
**Response Example**
```json
200 (OK)
Content-Type: application/json
{ "results":
{
"hash1": {
"blockid": "3123",
"result": "",
},
"hash2": {
"blockid": "3124",
"result": "",
}
}
}
```
**Error Response**
_E_HASHWRONG, E_HASHNOTFOUND_
### `txinfo/{hash}` {#txinfo-hash}
This request does not require login authorization.
**GET**/
Returns information about the transaction for the specified hash, including the
block ID and the number of confirmations. Also returns the contract name and its
associated parameters, if optional parameters are specified.
**Request**
- `hash`
> Transaction hash.
- `contractinfo` [Omitempty](#omitempty)
> Contract detail parameter identifier, to get the contract details related to
> this transaction, specify `contractinfo=1`.
```text
GET
/api/v2/txinfo/c7ef367b494c7ce855f09aa3f1f2af7402535ea627fa615ebd63d437db5d0c8a?contractinfo=1
```
**Response**
- `blockid`
> If the value is `0`, then no transaction was found for that hash.
- `confirm`
> The number of acknowledgements for this block _blockid_.
- `data` [Omitempty](#omitempty)
> If `contentinfo=1` is specified, the contract details are returned to this
> parameter.
**Response Example**
```json
200 (OK)
Content-Type: application/json
{
"blockid": "9",
"confirm": 11,
"data": {
"block": "9",
"contract": "@1NewContract",
"params": {
"ApplicationId": 1,
"Conditions": "true",
"Value": "contract crashci4b {\n\t\t\tdata {}\n\t\t\t}"
}
}
}
```
**Error Response**
_E_HASHWRONG_
### txinfoMultiple {#txinfomultiple}
This request does not require login authorization.
**GET**/
Returns the transaction-related information for the specified hash.
**Request**
- `data`
- `hashes`
> A list of transaction hashes.
- `contractinfo` [Omitempty](#omitempty)
> Contract detail parameter identifier, to get the contract details related to
> this transaction, specify `contractinfo=1`.
```text
data: {"hashes":["contract1hash", "contract2hash", "contract3hash"]}
```
```text
GET
/api/v2/txinfoMultiple
```
**Response**
- `results`
> The transaction hash is used as the key and the transaction detail is used
> as the value in the data dictionary.
>
> > `hash`
> >
> > > Trading Hash.
> >
> > > `blockid`
> >
> > If the value is `0`, then no transaction was found for that hash.
> >
> > > `confirm`
> >
> > > Number of acknowledgements for this block _blockid_.
> >
> > > `data`
> >
> > > If `contentinfo=1` is specified, the contract details are returned to
> > > this parameter.
**Response Example**
```json
200 (OK)
Content-Type: application/json
{ "results":
{
"hash1": {
"blockid": "3123",
"confirm": "5",
},
"hash2": {
"blockid": "3124",
"confirm": "3",
}
}
}
```
**Error Response**
_E_HASHWRONG_
### `/page/validators_count/{name}` {#page-validators-count-name}
This request does not require login authorization.
**GET**
Returns the number of nodes to be validated for the specified page.
**Request**
- `name`
> Page name with ecosystem ID in the format `@ecosystem_id%%page_name%`, for
> example `@1main_page`. If you don't have an ecosystem ID, then search in the
> first ecosystem page by default
```text
GET
/api/v2/page/validators_count/@2page_name
```
**Response**
- `validate_count`
> Specifies the number of nodes to be validated for the page.
**Response Example**
```json
200 (OK)
Content-Type: application/json
{"validate_count":1}
```
**Error Response**
_E_NOTFOUND, E_SERVER_
### `content|menu\|page/{name}` {#content-menu-page-name}
[Authorization](#authorization)
**POST**
Returns a tree of code JSON objects for the specified page or menu name, which
is the result of processing by the template engine.
**Request**
- `name`
> Page name or menu name with ecosystem ID in the format
> `@ecosystem_id%%page_name%`, for example:
>
> `@1main_page`.
>
> If no ecosystem ID is included, then search for the current ecosystem page
> or menu by default.
```text
POST
/api/v2/content/page/default
```
**Response**
- `menu` || `title`
> request _content/page/\..._ The name of the menu to which the page belongs
> when requesting it.
- `menutree`
> request _content/page/\..._ The page's menu JSON object tree when requested.
- `title` --head for the menu _content/menu/\..._
> request _content/menu/\..._ Menu title when requested.
- `tree`
> Page or menu JSON object tree.
**Response Example**
```json
200 (OK)
Content-Type: application/json
{
"tree": {"type":"......" ,
"children": [
{...} ,
{...}
]
},
}
```
**Error Response**
`E_NOTFOUND`
### `content/source/{name}` {#content-source-name}
[Authorization](#authorization)
**POST**
Returns a tree of coded JSON objects for the specified page name. Does not
execute any functions or receive any data. The returned JSON object tree
corresponds to the page template and can be used in the visual page designer. If
the page is not found, a 404 error is returned.
**Request**
- `name`
> Page name with ecosystem ID in the format `@ecosystem_id%%page_name%`, for
> example:
>
> `@1main_page`.
>
> If no ecosystem ID is included, then search for the current eco-page by
> default.
**Response**
```text
POST
/api/v2/content/source/default
```
- `tree`
> JSON object tree of the page.
**Response Example**
```json
200 (OK)
Content-Type: application/json
{
"tree": {"type":"......" ,
"children": [
{...} ,
{...}
]
},
}
```
**Error Response**
_E_NOTFOUND, E_SERVER_
### `content/hash/{name}` {#content-hash-name}
**POST**
Returns a SHA256 hash of the specified page name, or a 404 error if the page
cannot be found.
This request does not require login authorization. To receive the correct hash
when making requests to other nodes, you must also pass
_ecosystem,keyID,roleID,isMobile_ parameter. To receive pages from other
ecosystems, the ecosystem ID must be prefixed to the page name. For example:
`@2mypage`.
**Request**
```text
POST
/api/v2/content/hash/default
```
- `name`
> The name of the page with the ecosystem ID.
- `ecosystem`
> Ecosystem ID.
- `keyID`
> Account address.
- `roleID`
> Role ID.
**Response**
- `hash`
> Hexadecimal hash.
**Response Example**
```json
200 (OK)
Content-Type: application/json
{
"hash": "b631b8c28761b5bf03c2cfbc2b49e4b6ade5a1c7e2f5b72a6323e50eae2a33c6"
}
```
**Error Response**
_E_NOTFOUND, E_SERVER, E_HEAVYPAGE_
### content {#content}
**POST**
Returns the number of JSON objects for the page code from the **template**
parameter, if the optional parameter **source** is specified as `true or 1`,
then this JSON object tree does not perform any functions and receive data.
This JSON object tree can be used in the visual page designer.
This request does not require login authorization.
**Request**
- `template`
> Page code.
- `source`
> If `true or 1` is specified, the JSON object tree does not perform any
> functions and receives data.
```text
POST
/api/v2/content
```
**Response**
- `tree`
> JSON object tree.
**Response Example**
```json
200 (OK)
Content-Type: application/json
{
"tree": {"type":"......" ,
"children": [
{...} ,
{...}
]
},
}
```
**Error Response**
_E_NOTFOUND, E_SERVER_
### maxblockid {#maxblockid}
**GET**/ Returns the highest block ID on the current node.
This request does not require login authorization.
**Request**
```text
GET
/api/v2/maxblockid
```
**Response**
- `max_block_id`
> The highest block ID on the current node.
**Response Example**
```json
200 (OK)
Content-Type: application/json
{
"max_block_id" : 341,
}
```
**Error Response**
_E_NOTFOUND_
### `block/{id}` {#block-id}
**GET**/ Returns information about the specified block ID.
This request does not require login authorization.
**Request**
- `id`
> Block ID.
```text
POST
/api/v2/block/32
```
**Response**
- `hash`
> Block hash.
- `key_id`
> The address of the account that signed the block.
- `time`
> Block generation timestamp.
- `tx_count`
> Total number of transactions in the block.
- `rollbacks_hash`
> Block rollback hash.
- `node_position`
> The position of the block in the honor node list.
**Response Example**
```json
200 (OK)
Content-Type: application/json
{
"hash": "1x4S5s/zNUTopP2YK43SppEyvT2O4DW5OHSpQfp5Tek=",
"key_id": -118432674655542910,
"time": 1551145365,
"tx_count": 3,
"rollbacks_hash": "47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=",
"node_position": 0,
}
```
**Error Response**
_E_NOTFOUND_
### `avatar/{ecosystem}/{member}` {#avatar-ecosystem-member}
**GET**/ Returns the avatar of the user in the _member_ table (available without
login).
**Request**
- `ecosystem`
> Ecosystem ID.
- `member`
> The user's account address. (xxxx-... -xxxx)
```text
GET
/api/v2/avatar/1/1234-2134-... -4321
```
**Response**
The request header _Content-Type_ is the image type and the image data is
returned in the response body.
**Response Example**
```json
200 (OK)
Content-Type: image/png
```
**Error Response**
_E_NOTFOUND_ _E_SERVER_
### config/centrifugo {#config-centrifugo}
**GET**/ Returns the host address and port of centrifugo.
This request does not require login authorization.
**Request**
```text
GET
/api/v2/config/centrifugo
```
**Response**
Response result format `http://address:port`, e.g.: `http://127.0.0.1:8100`.
**Error Response**
_E_SERVER_
### updnotificator {#updnotificator}
**POST**/
(Discarded)
Sends all messages that have not yet been sent to the centrifugo notification
service. Sends only messages for the specified ecosystem and members.
This request does not require login authorization.
**Request**
- `id`
> Member's account address.
- `ecosystem`
> Ecosystem ID.
```text
POST
/api/v2/updnotificator
```
**Response Example**
```json
200 (OK)
Content-Type: application/json
{
"result": true
}
```
### Special instructions {#special-instructions}
#### Omitempty {#omitempty}
If the field has an omitempty attribute, it means that the field is an optional
parameter
#### Authorization {#authorization}
If the interface has an Authorization tag, it means that this interface requires
login authorization. Please add the Authorization to the request header. Here is
an example:
key = Authorization value = "Bearer + [login token](#login)"
```text
Authorization Bearer eyJhbGciOiJI..... kBZgGIlPhfXNZJ73RiZtM
```