]}` |
### Transaction receipts
Every transaction generates a receipt upon successful execution which contains the result and metadata such as fee and gas used. The `status` can be one of three values:
**SUCCESS**
Simple value transfer transactions and successful contract executions. For contract calls, the result is available in `ret`.
**ERROR**
Failed contract execution. The error message can be found in `ret`.
**CREATED**
Succesful contract deployment transaction. The created address can be found in `contractAddress`.
# Transaction Fees
The Meey protocol includes transaction fees that need to be paid according to the configuration of the network.
Gas is a numerical representation of execution and storage costs in the transaction and contract. But gas is not a fee. To calculate the fee, we need the gas price.
### Gas Price
Gas price is the GAS value corresponding to 1 gas. All transactions in a block have the same gas price. Gas price is determined by a DAO vote.
### Gas Limit
The gas limit allows the user to specify the maximum amount of gas used for transactions and contracts.
### Gas Table
#### Transaction
Transactions other than governance transactions consume `100,000 gas` by default. If you have a payload, additional gas will be used depending on the size.
**Payload gas**: (*Bytes of a payload* - 200) \* 5
#### Instructions
The table below shows gas usage for Lua bytecode.
| Name | GAS |
| ------------------------------------------------------------------------------ | --- |
| ISLT, ISGE, ISLE, ISGT, ISEQV, ISNEV, ISEQS, ISNES, ISEQN, ISNEN, ISEQP, ISNEP | 2 |
| ISTC, ISFC, IST, ISF, ISTYPE, ISNUM | 1 |
| MOV | 2 |
| NOT, UNM | 1 |
| LEN | 3 |
| ADDVN, SUBVN | 2 |
| MULVN, DIVVN, MODVN | 3 |
| ADDNV, SUBVN | 2 |
| MULNV, DIVNV, MODNV | 3 |
| ADDVV, SUBVV | 2 |
| MULVV, DIVVV, MODVV | 3 |
| POW | 3 |
| CAT | 3 |
| KSTR, KCDATGA, KSHORT, KNUM, KPRI, KNIL | 1 |
| UGET, USETV, USETS, USETN, USETP, UCLO, FNEW | 2 |
| TNEW | 2 |
| TDUP | 5 |
| GGET, GSET | 3 |
| TGETV, TGETS, TGETB, TGETR, TSETV, TSETS, TSETB, TSETM, TSETR | 2 |
| CALLM, CALL, CALLMT, CALLT, ITERC, ITERN | 10 |
| VARG | 5 |
| ISNEXT | 2 |
| RETM | 5 |
| RET, RET0, RET1 | 3 |
| FORI, FORL, ITERL, LOOP, JMP | 2 |
#### Built-in Functions
Gas usage for built-in functions provided by the Lua VM
| Name | GAS |
| ----------------------------------------------------- | ----------------------------------------------- |
| assert | 3 |
| error | 5 |
| getfenv | 5 |
| getmetable | 3 |
| ipairs | 3 |
| next | 3 |
| pairs | 3 |
| pcall | 10 |
| rawequal | 5 |
| rawget | 3 |
| rawset | 5 |
| select | 3 (length), 5 (get an element) |
| setfenv | 5 |
| setmetatable | 3 |
| tonumber | 5 |
| tostring | 5 |
| type | 2 |
| unpack | 5 + (2 \* *number of arguments*) |
| xpcall | 10 |
| string.byte, string.char | 3 + (1 \* *number of string units (arguments)*) |
| string.dump | 10 |
| string.find, string.gmatch, string.gsub, string.match | 3 + (5 \* *number of matching strings*) |
| string.format | 3 + (2 \* *number of format modifiers*) |
| string.lower | 3 + (1 \* *number of string units (argument)*) |
| string.rep | 3 + (2 \* *number of concatenation*) |
| string.reverse | 3 + (1 \* *number of string units (argument)*) |
| string.sub | 3 + (1 \* *number of string units (argument)*) |
| string.upper | 3 + (1 \* *number of string units (argument)*) |
| table.concat | 3 + (3 \* *number of arguments*) |
| table.insert | 3 + (3 \* *number of cells to move*) |
| table.maxn, table.minn | 3 + (3 \* *comparison count*) |
| table.sort | 3 + (5 \* *comparison count*) |
| math.abs, math.ceil, math.floor, math.pow | 3 |
| math.max, math.min | 3 + (1 \* *number of arguments*) |
| bit.tobit | 3 |
| bit.tohex | 5 |
| bit.bnot | 2 |
| bit.bor, bit.band, bit.xor | 3 + (2 \* *number of arguments*) |
| bit.lshift, bit.rshift, bit.ashift, bit.rol, bit.ror | 3 |
| bit.bswap | 2 |
# Keystore
{% hint style="info" %}
Securing private keys is the responsibility of client software, but Meey has a recommended storage format for increased portability. This storage format is also used internally when storing accounts in meeycli.
{% endhint %}
This so-called Keystore format defines a file format (json) and encryption scheme.
### File format
Filename: `{address}__keystore.txt`
```
{
"meey_address": "Amdxxxx",
"ks_version": "1",
"kdf": {
"algorithm": "algorithm_name",
"params": {
"some_param": "some_value"
},
"mac": "mesasge_authentication_code"
},
"cipher": {
"algorithm": "algorithm_name",
"params": {
"some_param": "some_value"
},
"ciphertext": "dxxxx",
}
}
```
### Rules
* Version field is for choosing cipher algorithm. If version updates, cipher algorithm would be updated (also format can change).
* Every file has its own algorithm and parameters per version. If any of the parameters break, an error should be thrown.
* File name is ‘{address}\_\_keystore.txt’ or ‘{alias}\_\_keystore.txt’
* File name is used to identify keystore file. Duplicates are not allowed.
* For the alias file, you can have same keystore file representing same account using different alias. That’s fine.
* Address must be a valid base58-check encoded address. Alias must be form of `[a-zA-Z0-9]+`
### Examples
**Encrypt**
```
cipherText = AES_CTR.encrypt(rawPrivateKey, encryptionKey[0:16], nonce)
mac = Sha256(encryptionKey[16:32] + cipherText)
keystore = {
"meey_address": "Amdxxxx",
"ks_version": "1",
"kdf": {
"algorithm": "scrypt",
"params": scryptParams,
"mac": mac
},
"cipher": {
"algorithm": "aes-128-ctr",
"params": {
"iv": nonce
},
"ciphertext": cipherText
}
}
```
**Decrypt**
```
encryptionKey = Scrypt(rawPassword, keystore.kdf.params)
mac = Sha256(encryptionKey[16:32] + json.cipher.ciphertext)
if keystore.kdf.mac != mac {
throw "invalid mac"
}
rawPrivateKey = AES_CTR.decrypt(json.cipher.ciphertext, encryptionKey[0:16], json.cipher.params.iv)
```
**Recommended parameters**
```
{
kdfAlgorithm: 'scrypt',
cipherAlgorithm: 'aes-128-ctr',
kdfParams: {
dklen: 32,
n: 1 << 18,
p: 1,
r: 8,
},
}
```
# Peer Connect
### Node Discovery
When the Meey server starts running, you need a way to connect to the network. To do this, you need to know and connect to other Meey server nodes already connected to the chain. Meey does this using several methods.
#### Query wezen
Wezen keep list of meey server nodes, such like DNS. Meey server connect and query to official Meey Wezen automatically, if the chain is Official MeeyMainNet or MeeyTestNet.
You can build and run custom Wezen for your private chain or custom public chain. You should configure to use custom Wezen by modifying config file.
#### Designate Peer
You can add a list of designated known peers to connect to at boot time in configuration file using the option ‘npaddpeers’.
#### Dynamic peer discovery
Meey server requests peer list from other connected peers as well as Wezen if it cannot find enough peers.
### Peer connect process
The network communication of Meey server operates on libp2p basis, and libp2p is responsible for encryption and node distinction at transmission level. After a tcp session is created, both peers start the handshake operation.
#### Peer Handshake
In the Handshake phase, peers exchanges each other’s version, chain ID and state to determine whether to connect. If the other node version is not supported by the current server or the operating chain ID is different, the connection is stopped. Once the handshake is successful, the difference in block height is compared and synchronization started.
#### Keep Alive
Meey server maintains a connection-based communication. Both peers disconnect when the internally defined retention score increases beyond a certain level. This score decreases to a low level when a query is requested, and increases when a bad block or TX notification is sent.
#### Peer blacklist
When an internally defined ban score exceeds a certain level, the Meey server blocks the peer’s connection. This score increases due to the connection being disconnected due to exceeding the connection maintenance score, etc., and the blocking period is also changed by calculating the score or the number of blocking times. You can also permanently block by specifying a block address in the configuration file.
# Block Management
This article describes implementation details of management of blocks in the Meey server. It is aimed at blockchain server developers.
### Block generation
The block factory is responsible for generating blocks and part of the consensus engine.
The consensus engine manages when blocks are created on which nodes. Meey uses dPOS by default. A new block producer is selected every second.
The process for creating blocks in the block factory is as follows.
1. Select transactions from from mempool
2. Perform a transaction one by one. If the execution is successful, the transaction is included in the block.
3. If the block size and time limit are exceeded, the transaction is no longer included.
4. Create blocks that contain executed transactions and add signatures to blocks.
The block factory sends the generated blocks to the chain service for propagation and storage.
### Notify block
Blocks passed to the chain service are propagated to the connected peer nodes and stored in the database.
The chain service of a node that received the block verifies the block, executes the transactions, and adds the block to its own database.
### Save block
The chain service stores the generated blocks in the DB for permanent storage. It also stores additional meta information to store connection information about the chain.
Meey uses the Badger database as its permanent storage. Badger stores data in key/value form and supports the concept of transactions similar to a typical database.
**Information stored in the DB is as follows.**
The DB is managed in two separate categories, ChainDB and StateDB. This article describes the ChainDB used to store chain information.
#### Block info
This information is used to search for blocks in a chain using a hash. Typically, when a block is requested as a hash from another node, the Hash is searched for and responded to the block with a key.
| Key | Value |
| ------------- | ------------------------ |
| Hash of Block | serialized data of Block |
#### Chain info
Chain info is the information that indicates when a block is connected to the main branch.
If the main branch is not connected, that is, only block info is saved and the chain info is not stored.
You can search the blocks of every height of the main branch using the chain info. You can know the height of the top block of the chain.
Chain info is also used to determine whether the block belongs to the main branch or the sub branch.
| Key | Value |
| ---------------- | ---------------------------------- |
| Number of Block | block hash |
| Latest block Key | latest block number of main branch |
#### Transaction Info
TX info is meta information of the transaction that was performed in the main branch. If you search the DB with transaction hash, you can see which block the transaction is stored in and where the transaction is stored in the block.
The contents of the transaction are not saved separately. Therefore, in order to know the contents of the actual transaction, you must search Block info using Block hash and index found in TX info.
| Key | Value |
| ---------------- | ------------------------------------------- |
| Transaction hash | (Block Hash, index of transaction in block) |
# Chain Management
This article describes implementation details of chain management in the Meey server. It is aimed at blockchain server developers.
The chain service is responsible for managing the chain. It performs the following tasks in large part:
1. Validation
2. Insert block to chain
3. Reorganization
4. Synchronization
### Block validation
The blocks received in the network may not be valid, so a number of checks are made.
#### Pre-execution execution
The validator module ensures that the block was generated from a valid BP and the transaction contained in the block was not forged.
* **Consensus validation:** Validate the block generated by the valid BP through block creation time and signature.
* **Transaction merkle validation:** Validate that the transactions were not forged. The verifier module generates a merkle tree with the transactions and checks if it is the same as the transaction merkle root stored in the block header.
#### Post-execution validation
These checks ensure that the results of the transaction contained in the block are the same as the results of the BP node that generated the block.
* **State root validation:** Checks if the changed state root node hash is the same as the blocksRootHash stored in the block head.
* **Receipt merkle validation:** Generates a merkle tree with the receipts generated as a result of the transactions and checks if they are identical to the receipts stored in the block header.
### Insert block into chain
There are two cases in which the chain service adds blocks:
**1.Block generated by block factory**
When it is a BP node’s turn, it generates new blocks in the block factory.
The block factory performs all transactions and forwards the block to the chain service. The execution results are included with the block.
The execution results include the results of the transaction, receipt, and state changed entry indicating the change to the account.
The chain service stores information related to blocks in the ChainDB and information about accounts in the StateDB.
**2. Block received from another peer node**
For blocks received from other peer nodes, there are three main cases:
* **Orphan block:** This is the case if the parent block has not yet been stored in the DB. Orphan blocks are stored in the orphan block cache on memory. Then, when the parent block is received, it is removed from the organ block cache and reprocessed.
* **Side branch block:** In case the parent block is stored but is not part of the main branch. In this case, the block is not performed and only the block info{hash, block} is stored.
* **Main branch block:** In case the head of the main branch is the next block. In this case, the blocks are stored after performing the transactions.
The process for storing blocks in the main branch is as follows:
1. Validation before execution
2. Execute transactions
3. Apply changed account entries state merkle tree
4. Validate after execution
5. Save state merkle tree to StateDB
6. Save chain meta data to ChainDB
### Reorganization
The chain service selects and maintains the longest chain as the main branch. The side branches are not executed and only the block info is stored in the DB. If the side branch received from another peer is longer than the main branch held by the node, the side branch is changed to the main branch. This is called the reorganize process.
The reorganization is performed as follows.
1. **Find common ancestor:** Syncer finds the last common ancestor block of the main branch and side branch.
2. **Rollback master branch:** State is reset to the point at which the common ancestor block was executed
3. **Rollforward side branch:** Syncer runs from the next number of the common ancestor block to the head block of the side branch. At this time, only StateDB is changed and Chain info and Tx info are not changed.
4. **Swap chain meta:** Syncer do not change the chain info during rollback and rollforward to atomically change the chain. Change the chain meta information after the previous process has been successfully completed. At this time, chain info and transaction info are deleted for the rollbacked block, and new chain info and transaction info are added for the rollforwarded block.
Transactions belonging to rollbacked blocks but not included in rollforwarded blocks are returned to mempool. This is to prevent transaction loss.
### Synchronization
When you add a new node or restart a node that was temporarily stopped, you need to get the latest chain information from existing nodes. This is called the synchronization process.
The situation that causes sync is as follows:
* When the peer goes through a handshake process to connect, the height of the chain of the remote peer is higher than the current node
* If the height of the block notified in the peer is higher than the head of the current main branch
The syncer specifies the node that sent the block that caused the sync to the target node and synchronizes with the chain of that node.
For synchronize a long chain, a large amount of block information must be received from the peer node. This is likely to cause a performance degrade at the peer node. Therefore, it gets information from as many peers as possible to distribute the load.
#### Synchronize step
1. **Find common ancestor:** Syncer finds the last common ancestor of the current node chain and the target node chain.
2. **Get hashes:** It gets the hashes of the block after the common ancestor from the target node.
3. **Get blocks:** N blocks are requested from all valid peers connected to the current node.
4. **Insert blocks to chain:** The received block is added to the chain using the chain service.
2, 3, and 4 are performed in parallel. Most of the time is spent in the insert part of the chain.
# Technical Details
# Network Architect
The peer role of the MEEY Network distinguishes its external network from the internal network. In this way, we can save network costs between nodes more effectively than through the traditional way
#### Internal Network
* Block Producers (BP): The BP uploads blocks and broadcasts those blocks to other BPs and Agents within the same internal network.
* Agents: The Agent is the BP’s representative and communicates with other nodes in the external network and broadcasts the block information to other BPs as soon as possible.
#### External Network
* Watchers: The Watcher syncs and provides the API service.
### The objective of Agents
Basically their role is to maximize time efficiency in block broadcasting. The Agents actively connect with other Agents and BPs in the open network after verifying their identities.
Agents will propagate the blocks produced by BPs to Agents and other BPs in a manner that focuses on speed and latency, and immediately sends new block notifications sent by those Agents and BPs to the representative BP. On the other hand, Agents propagate notifications to the Watcher in ways that make efficient use of the network.
### Identity verification function
Each node confirms the qualification of a BP based on BP information and result of voting. Agents also confirm the qualification of Agents based on certification issued by BPs.
# Config Network
### Genesis block configuration
The genesis block is the first block created on a new chain according to a predefined specification. If you want to bootstrap your own Meey blockchain, you will need to configure and create the genesis block. All nodes producing blocks and syncing with the network need to use the same genesis block.
**Example genesis**
```
{
"chain_id":{
"magic": "[insert an identifier string for your network]",
"public": false,
"mainnet": false,
"coinbasefee": "1000000000",
"consensus": "dpos"
},
"timestamp": 1548918000000000000,
"balance": {
"[insert address from genesis]": "470000000000000000000000000",
"[insert address from bp01]": "10000000000000000000000000",
"[insert address from bp02]": "10000000000000000000000000",
"[insert address from bp03]": "10000000000000000000000000"
},
"bps": [
"[insert text from bp01.id]",
"[insert text from bp02.id]",
"[insert text from bp03.id]"
]
}
```
| Key | Type | Explanation |
| ------------- | ------ | ---------------------------------------------------------------------------------------------------- |
| chain\_id | obj | |
| – magic | string | A name identifier used to distinguish different chains.
Example: yourchain.network
|
| – public | bool | If this chain is for a public (true) or private network.
This may affect certain features.
|
| – mainnet | bool | If this is the main network (true) or a sidechain for another network. |
| – consensus | string | This blockchain’s consensus type (dpos) |
| – coinbasefee | string | The default transaction fee amount |
| timestamp | number | The genesis block’s creation timestamp in nanoseconds |
| balance | obj | A mapping of addresses and allocated balances |
| bps | list | A list of fallback block producer peer ids. |
### Creating peer identification (Optional Step)
Every peer (i.e. instance of meeysvr) is identified by a peer id, derived from its public key. If unspecified, meeysvr creates these automatically, but you may want to do it manually to control the generation of keys and make backups. You can use the CLI to do that:
```
meeycli keygen your-keyname
# Using Docker:
docker run --rm -v $(pwd):/tools/ meey/tools meeycli keygen your-keyname
```
You then need to specify the path to the generated your-keyname.key file in the Meey configuration:
```
...
[p2p]
npkey = "/meey/your-keyname.key"
...
```
### Internal Zones
There may be several BPs in one private network; these BPs can be connected directly to spread the blocks without having to pass through Agents. And these BPs can be more efficient in resource use by sharing Agents than by each BP having Agents.
For efficient use of network and computing resources, Agent categorizes networks to internal and external, delivering only internal to external, or vise versa.
The Agent node connects the client BPs in the internal network with other BPs or Agents in the external network. The Agent passes blocks generated by a client to the BPs or Agents of the external network as quickly as possible, while the blocks notified by the external BPs or Agents are passed to the client BPs.\
\
**Config Example**
NOTE: Configuring BP and Agent are advanced topic, and wrong configuration can cause performance degradation or abnormal operation. So this configurations are more strictly checked than other settings; read the document carefully and set it up.
Suppose there is a foundation named Wesoha, and the foundation decided to participate in the Meey network. The foundation establishes three BP nodes, one Agent node, and one node for TX registration and monitoring in the private network. The private address and peer ID of each node are as follows.
```
BP1 : 192.168.25.21 / 16Uiu2HAmH1Eup6qLSQg3Bk7B5QbrVPk6Bzw7upHhZ74ZTS8kM
BP2 : 192.168.25.22 / 16Uiu2HAkzW5j6c6w9BhRnuudHuYc3Kqk4aNi4KbuoaYwVDx3HkS
BP3 : 192.168.25.23 / 16Uiu2HAkvwrouZCrCSG8BqMM1v9GRj11jfjfjfhby5fAXgbCg
Agent : 192.168.25.31 / 16Uiu2HAm7P7quSBCxPHe89wNUYwCki1M8F45kMMRjw5M6bQdVWEv
Watcher: 192.168.25.32 / 16Uiu2HAkvQYs1e6jVbpAeMfTNpDgUYhxry6gMRQnMAqymVL2Z45
```
The foundation registered the mainnet.wesoha.io domain to join the chain network and forwarded the IP address of the domain to the agent machine.
BPs and Watcher allow access only from the Foundation’s internal network and are linked to the public network only through Agent.
The connection between Agent and client BP is built on the secured environment that the network manager cares about; BP and Agent must specify each other correctly in configuration.
**Configuration of BP Node**
BP disables npexposeself, npdiscoverpeers, and npusewezen settings so that they are not exposed to the outside and do not automatically connect to external nodes. BP node also set agent field to peer id of agent node.
```
# MEEY TOML Configration File (https://github.com/toml-lang/toml)
# base configurations
datadir = "./data"
enableprofile = false
personal = false
[p2p]
npkey = "bp01.key" # Name of key file of node
npaddpeers = [
"/ip4/192.168.25.22/tcp/7846/p2p/16Uiu2HAkzW5j6c6w9BhRnuudHuYc3Kqk4aNi4KbuoaYwVDx3HkS",
"/ip4/192.168.25.23/tcp/7846/p2p/16Uiu2HAkvwrouZCrCSG8BqMM1v9GRj11jfjfjfhby5fAXgbCg",
"/ip4/192.168.25.31/tcp/7846/p2p/16Uiu2HAm7P7quSBCxPHe89wNUYwCki1M8F45kMMRjw5M6bQdVWEv",
"/ip4/192.168.25.32/tcp/7846/p2p/16Uiu2HAkvQYs1e6jVbpAeMfTNpDgUYhxry6gMRQnMAqymVL2Z45"
]
npusewezen = false
npexposeself = false # peer is advertised by wezen or other peers
npdiscoverpeers = false # peer will not try to discover and connect other peers except for peers listed in npaddpeers
peerrole = "producer"
agent = "16Uiu2HAm7P7quSBCxPHe89wNUYwCki1M8F45kMMRjw5M6bQdVWEv"
[blockchain]
blockchainplaceholder = false
coinbaseaccount = "[ADDRESS OF CONBASE ACCOUNT]"
[mempool]
showmetrics = true
dumpfilepath = "./data/mempool.dump"
[consensus]
enablebp = true
```
**Configuration of Agent Node**
Agent activates npexposeself, npdiscoverpeers, npusewezen settings, and also sets addresses that can be accessed from the outside, so that they can connect to other nodes in the public network. Also set producers field to a list of the client BP’s peer ids and internal zones.
```
# MEEY TOML Configration File (https://github.com/toml-lang/toml)
# base configurations
datadir = "./data"
enableprofile = false
personal = false
[p2p]
netprotocoladdr = "agent.wesoha.com"
npkey = "agent01.key" # Name of key file of node
npaddpeers = [
"/ip4/192.168.25.21/tcp/7846/p2p/16Uiu2HAmH1Eup6qLSQg3Bk7B5QbrVPk6Bzw7upHhZ74ZTS8kM",
"/ip4/192.168.25.22/tcp/7846/p2p/16Uiu2HAkzW5j6c6w9BhRnuudHuYc3Kqk4aNi4KbuoaYwVDx3HkS",
"/ip4/192.168.25.23/tcp/7846/p2p/16Uiu2HAkvwrouZCrCSG8BqMM1v9GRj11jfjfjfhby5fAXgbCg",
"/ip4/192.168.25.32/tcp/7846/p2p/16Uiu2HAkvQYs1e6jVbpAeMfTNpDgUYhxry6gMRQnMAqymVL2Z45"
]
npusewezen = true
npexposeself = true # peer is advertised by wezen or other peers
npdiscoverpeers = true # peer will not try to discover and connect other peers except for peers listed in npaddpeers
peerrole = "agent"
producers = [
"16Uiu2HAmH1Eup6qLSQg3Bk7B5QbrVPk6Bzw7upHhZ74ZTS8kM",
"16Uiu2HAkzW5j6c6w9BhRnuudHuYc3Kqk4aNi4KbuoaYwVDx3HkS",
"16Uiu2HAkvwrouZCrCSG8BqMM1v9GRj11jfjfjfhby5fAXgbCg"
]
internalzones = ["192.168.25.1/24"]
[blockchain]
[mempool]
showmetrics = true
dumpfilepath = "./data/mempool.dump"
[consensus]
enablebp = false
```
### NTP
Timing is critical in a blockchain, so it’s better to configure the machines’ time setup manually:
```
sudo bash
apt-get install chrony
nano /etc/chrony/chrony.conf
```
```
server time1.google.com iburst
server time2.google.com iburst
server time3.google.com iburst
server time4.google.com iburst
```
```
systemctl restart chronyd
chronyc makestep
```
**Create genesis block**
```
./bin/meeysvr init --genesis /root/.meey/genesis.json --home /root/.
```
# DAO Voting
Decentralized Autonomous Organizations
With Meey network certain parameters of the public mainnet are now subject to a DAO vote. Everyone who has a stake can participate in the voting process, making Meey on-chain governance much more decentralized. What’s more, the Meey foundation decided to sponsor a reward for voting! For every block, one of the voters is chosen, with a probability according to their contribution.
In order to vote, you need to stake at least 10000 Meey.
### 1. System Voting
1. **BP - Block producers:** This vote determines the block producers that will be assigned in the DPOS consensus algorithm.
2. **BPCOUNT - Block producer count:** This vote determines the number of block producers that will be assigned in the DPOS consensus algorithm
3. **STACKINGMIN - Staking Minimum:** This vote determines the minimum amount (in gas) required for staking.
4. **GASPRICE - Gas Price:** This vote determines the gas price (in gas) used to calculate transaction fees
5. **NAMEPRICE - Name Transaction Price:** This vote determines the amount (in gas) required for name transactions (create and update). Governance transactions are otherwise free, so this fee prevents spam and name squatting.
### 2. Governance Voting
Governance Voting is the new on-chain governance system that aims to be a business-minded DAO and decentralized decision-making framework.
MEEY token holders can participate and contribute in making governing decisions for the MEEY ecosystem through Governance Voting. Governance Voting will be accelerating MEEY to become a democratic, fully self-sustaining and open ecosystem.
### 3. FAQs
#### What are the time restrictions for staking and voting?
After every action (both staking and voting), you need to wait for 24 hours before being able to do the next action. The only exception is the very first time: one time, you can conduct all of the actions at once. The diagram at the bottom of this page shows an example daily schedule and how it affects your current totals.
#### What is voting power?
When you cast a vote, it is weighed by your currently staked amount. This is called the power of your vote, or voting power. Your total voting power is the sum of all your votes' power.
#### If I can only do one action per 24 hours, is it better to stake first or vote first?
If you want to change your stake, you should do that first to maximize your reward. Your votes are weighed based on your currently staked amount.
#### How are rewards calculated?
A reward (currently 0.16 meey) is paid out with every block (block rate: 1 second). The winner is selected randomly, with the chance depending on your total voting power in relation to everybody's voting power. Over a longer time period (e.g. 24 hours), your total received reward will be very close to the statistically expected one. In mathematical terms, your expected daily reward is (myTotalVotePower / allVotePower) \* (0.16) \* (60 \* 60 \* 24).
#### When should I increase my stake?
If you have additional meey to stake (for example because you received some rewards), it makes sense to increase your stake and vote again to increase your chances of receiving rewards. Your chance will increase roughly by the same percentage that your voting power increased, so you can calculate if it is worth your while.
#### What happens when I decrease my stake (unstake)?
When your stake is decreased, your voting power of your current votes is automatically adjusted. You don't need to vote again.
#### Should I vote for the same vote more than once?
You only need to vote again if you increased your stake or if you changed your mind about the candidate you voted for. If your stake is unchanged, voting again has no effect on your reward.
#### Should I vote for all votes?
Yes, your reward is based on your total voting power, which is the sum of all your current votes.
#### How can I know which vote I haven't voted for yet?
Check the Votes overview table on your account detail page. The voting power for each vote is the same as your staked balance at the time of voting. If you increased your stake, you can tell from the difference for which votes you already voted again and which you have yet to vote for.
#### What's an example schedule for staking and voting?
In this example, someone staked 10000 meey on the first day and voted in all votes. Ten days later, they increased their stake by 5000 meey. For the next five days, they update their votes. With every updated vote, the total voting power increases, and thus their chance to win the reward.
# Platform
# MeyCoin Server
## Using Docker
The easiest way to run a local MeyCoin server is using Docker. An up-to-date Docker image is always available on Docker Hub.
```
$ docker run -p 7845:7845 meycoin/node
```
You can pass arguments to the server like this:
```bash
$ docker run -p 7845:7845 meycoin/node meycoinsvr --testmode
```
To supply your own config file, use:
```bash
$ docker run -p 7845:7845 -v $(pwd)/config.toml:/meycoin/config.toml meycoin/node meycoinsvr --config /meycoin/config.toml
```
## Building from source
*Prerequisites*
* Go1.12.5+ -
* CMake 3.0.0 or higher -
* Optional: Protobuffer -
### Linux
1.Install dependencies
```bash
sudo apt update
sudo apt upgrade
sudo apt install build-essential libssl-dev m4 -y
```
2.Install CMake
```bash
wget https://github.com/Kitware/CMake/releases/download/v3.17.3/cmake-3.17.3.tar.gz
tar -zxvf cmake-3.17.3.tar.gz
cd cmake-3.17.3
sudo ./bootstrap
sudo make
sudo make install
cmake --version
```
3.Install Go
```bash
wget https://golang.org/dl/go1.15.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.15.linux-amd64.tar.gz
nano ~/.profile
export GOROOT=/usr/local/go
export GOPATH=$HOME/go
export PATH=$GOPATH/bin:$GOROOT/bin:$PATH
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:${GOPATH}/src/github.com/meeypioneer/meycoin/libtool/lib
source ~/.profile
```
4.Install MeyCoin Server
```bash
go get -d github.com/meeypioneer/meycoin
cd ${GOPATH}/src/github.com/meeypioneer/meycoin
git submodule init && git submodule update
make
```
### MacOS
1.If you haven’t already, install [homebrew](https://brew.sh/).
2.Install dependencies
```bash
brew install go
brew install cmake # optional
brew install protobuf # optional
nano ~/.zshrc
export GOPATH=$HOME/go
export GOROOT="$(brew --prefix golang)/libexec"
export PATH="$PATH:${GOPATH}/bin:${GOROOT}/bin"
source ~/.zshrc
```
3.Set environment
```bash
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:${GOPATH}/src/github.com/meeypioneer/meycoin/libtool/lib
```
4.Install MeyCoin Server
```bash
go get -d github.com/meeypioneer/meycoin
cd ${GOPATH}/src/github.com/meeypioneer/meycoin
git submodule init && git submodule update
make
```
## Run Server
```bash
./bin/meycoinsvr
```
# Wezen Server
Wezen is a server that provides node discovery for Wezen server.
## Features
* MeyServer nodes can query addresses of other MeyServer nodes. In this case, the chain of the MeyServer node and the chain of Wezen must be the same.
* MeyServer nodes can register itself with Wezen. Wezen checks to see if it can connect to the MeyServer node and adds it to the node list.
* One Wezen server per designated block chain
## Building WEZEN Server
This section describes how to build Wezen from source without using the Docker. Wezen is available as a sub-module in the MEYCOIN project.
1. Get the source from github.com/meeypioneer/meycoin.
2. Build the wezen executable with `make wezen`.
## Configuration
Four files are used to set Wezen behavior.
1. Private key file: PK file to use for Wezen communication. It uses the same format as meycoinsvr private key file.
2. Genesis file: Contains the chain information of nodes to be provided by Wezen. Use the same format as the genesis file used to initialize meycoinsvr.
3. Wezen configuration file: Determines the overall operation of Wezen. It also specifies the path to other configuration related files.
4. Log configuration file: The file name is meeylog.toml, and it uses the same format as the file used by meycoinsvr.
#### Create private key file
It can be generated by meycoincli using the keygen command
```
meycoinocli keygen mychain-wezen
Wrote files mychain-wezen.{key,pub,id}.
```
#### Create genesis file
```
{
"chain_id":{
"magic": "mychain.test",
"public": false,
"mainnet": false,
"coinbasefee": "1000000000",
"consensus": "dpos"
},
"timestamp": 1548918000000000000,
"balance": {
},
"bps": [
]
}
```
**Wezen configuration file**
```
authdir = "/blockchain/wezen/auth" # base directory for files about authentication and authorization
[rpc]
netserviceaddr = "127.0.0.1" # RPC access address. The default setting is 127.0.0.1, which allows RPC access only on the local machine and blocks RPC connections remotely.
netserviceport = 8915
[p2p]
netprotocoladdr = "[real IP address]" # An externally accessible IP address or domain name
netprotocolport = 8916
npbindaddr = ""
npkey = "mychain-wezen.key" # Location of private key file
[wezen]
allowprivate = true # Whether to allow the private address of the node's access address. Used when building Wezen for private chains operated within a test or private network.
genesisfile = "[location of genesis file]" # Genesis file location
enableblacklist = false # Whether to turn on blacklist or not. blacklist entries will be saved in
```
**Logging options**
It is possible to customize the log output format of all Meey CLI tools using a file called meeylog.toml placed in the current working directory
```
level = "info" # default log level
formatter = "json" # format: console, console_no_color, json
caller = true # enabling source file and line printer
timefieldformat = "RFC3339"
[chain]
level = "info" # optional, log level for 'chain' module
[dpos]
level = "info"
[p2p]
level = "info"
[consensus]
level = "info"
[mempool]
level = "info"
[contract]
level = "info"
[syncer]
level = "info"
[bp]
level = "info"
```
## Running Wezen
**Using Docker**
```
docker run -d -w /tools -v /blockchain/wezen:/tools -p 8916:8916 -p 8915:8915 --restart="always" --name wezen-node meey/wezen wezen --home /tools --config /tools/wezen-conf.toml
```
**Manually**
```
./wezen --config wezen-conf.toml
```
# Smart Contracts
Meey provides its own smart contract platform for implementing various business logic on the blockchain.
To create smart contracts for Meey, you can use the [Lua scripting language](http://www.lua.org/about.html).
Lua is a powerful, efficient, lightweight, embeddable scripting language. It has a simple procedural syntax with a powerful data description structure. Lua supports a variety of programming methods: procedural programming, object-oriented programming, functional programming.
We use [LuaJIT 2.1.0](http://luajit.org/luajit.html) as the VM. LuaJIT is a Just-In-Time Compiler (JIT) for the Lua programming language.
You can learn the Lua programming language through the following documents:
* [Lua 5.1 Reference Manual](http://www.lua.org/manual/5.1/)
* [Programming in Lua](http://www.lua.org/pil/) (The second edition was aimed at Lua 5.1)
# Hello World
This is the most basic lua smart contract to store and retrieve states in Meey. You can save a name on the blockchain with the contract call function. And you can print ‘hello …’ with the query function.
```
-- Define global state variables
state.var {
Name = state.value(),
My_map = state.map()
}
-- Initialize the state variables
function constructor()
-- a constructor is called only once at the contract deployment
Name:set("world")
My_map["key"] = "value"
end
-- Update the name
-- @call
-- @param name string: new name
function set_name(name)
Name:set(name)
end
-- Say hello
-- @query
-- @return string: 'hello ' + name
function hello()
return "hello " .. Name:get()
end
-- register functions to expose
abi.register(set_name, hello)
```
This is explained based on using cli. Variables used in this example are
* Account to deploy and execute a contract: AmPPCH5aMeHnaBPJ782UynpdFa612d8runz2zY83P4AcPHqTrhqL
* Cli commands in this page need a meeysvr with enable personal feature
### Check Account and Balance
First, you need an account with enough balance to deploy and execute smart contracts. (If you don’t) Import or Unlock Account to meey server.
### Compile Contract
Copy above code and save it to a file (e.g. helloword.lua). And Compile using the `meeyluac` compiler
```
./bin/meeyluac --payload lua_file_location.lua
```
```
./bin/meeycli contract deploy AmPPCH5aMeHnaBPJ782UynpdFa612d8runz2zY83P4AcPHqTrhqL --payload 37mGLDoCPNDQw7HbCG5WPfcM3E3cLhqhgE2V2UJK
```
### Get receipt of contract
Look up the actual contract address with the transaction ID above.
```
./bin/meeycli receipt get DyJg7jkw7AUT9ZNWyBUhwkR56V2E2HhZMGRSexamsUcJ
{
"BlockNo": 1745,
"BlockHash": "9NifJDJSTU9ibXsabRbr1VNxs2YeU6gC6ZMeNbAmCw8Z",
"contractAddress": "AmhTVMdngSCs3xJ5XLAZHm8MGfAdnsNEvWvtpBhRnVky4fbnLZFB",
"status": "CREATED",
"ret": {},
"txHash": "DyJg7jkw7AUT9ZNWyBUhwkR56V2E2HhZMGRSexamsUcJ",
"txIndex": 0,
"from": "AmPPCH5aMeHnaBPJ782UynpdFa612d8runz2zY83P4AcPHqTrhqL",
"to": "",
"feeUsed": 4080000000000000,
"gasUsed": 0,
"feeDelegation": false,
"events": []
}
```
If the status is not ‘CREATED’, it may not be included in the block yet, or there may be an error. Wait a while until the transaction is included in the block. Or check the server’s error log.
### Get ABI of contract
Look up ABI of contract with the contract address above.
```
./bin/meeycli contract abi AmhTVMdngSCs3xJ5XLAZHm8MGfAdnsNEvWvtpBhRnVky4fbnLZFB
{
"version": "0.2",
"language": "lua",
"functions": [
{
"name": "hello"
},
{
"name": "set_name",
"arguments": [
{
"name": "name"
}
]
},
{
"name": "constructor"
}
],
"state_variables": [
{
"name": "Name",
"type": "value"
},
{
"name": "My_map",
"type": "map"
}
]
}
```
### Query Initial State
You can query the generated contract in the following way.
```
./bin/meeycli contract query AmhTVMdngSCs3xJ5XLAZHm8MGfAdnsNEvWvtpBhRnVky4fbnLZFB hello
```
You can see that the name ‘world’ assigned by the constructor is output.
### Call Contract
You can change the name recorded in the block chain as follows:
```
./bin/meeycli contract call AmPPCH5aMeHnaBPJ782UynpdFa612d8runz2zY83P4AcPHqTrhqL AmhTVMdngSCs3xJ5XLAZHm8MGfAdnsNEvWvtpBhRnVky4fbnLZFB set_name '["meeychain"]'
```
### Query Changed State
If you look at the results again, it has changed.
```
./bin/meeycli contract query AmhTVMdngSCs3xJ5XLAZHm8MGfAdnsNEvWvtpBhRnVky4fbnLZFB hello
```
### Query contract variable with merkle proof
#### Value
```
./bin/meeycli contract statequery AmhTVMdngSCs3xJ5XLAZHm8MGfAdnsNEvWvtpBhRnVky4fbnLZFB Name --compressed
```
#### Map
```
./bin/meeycli contract statequery AmhTVMdngSCs3xJ5XLAZHm8MGfAdnsNEvWvtpBhRnVky4fbnLZFB My_map key --compressed
```
#### Array
```
./bin/meeycli contract statequery AmhTVMdngSCs3xJ5XLAZHm8MGfAdnsNEvWvtpBhRnVky4fbnLZFB array_name array_index --compressed
```
By default, the returned state is the one at the latest block, but you may specify any past block’s state root.
```
./bin/meeycli contract statequery AmhTVMdngSCs3xJ5XLAZHm8MGfAdnsNEvWvtpBhRnVky4fbnLZFB var_name --root "9NBSjkcNTdE5ciBxfb52RmsVW7vgX5voRsv6KcosiNjE"
```
# Token Issue
This is an example for token system. It show how to build dApp
```
------------------------------------------------------------------------------
-- Safe maths
------------------------------------------------------------------------------
local M = {}
function M.add(a, b)
if a == nil then a = 0 end
if b == nil then b = 0 end
local c = a + b
assert(c >= a, "number overflow")
return c
end
function M.sub(a, b)
if a == nil then a = 0 end
if b == nil then b = 0 end
assert(b <= a, "first value must be bigger than second one")
local c = a - b
return c
end
function M.mul(a, b)
if a == nil then a = 0 end
if b == nil then b = 0 end
local c = a * b
assert(a == 0 or c/a == b, "number overflow")
return c
end
function M.div(a, b)
if a == nil then a = 0 end
if b == nil then b = 0 end
assert(b > 0, "second value must be bigger than 0")
c = a / b
return c
end
Mixer = {}
MixerMetatable = { __index = Mixer }
setmetatable(Mixer, {
__call = function(cls, ...)
return cls.new(...)
end
})
function Mixer.new(...)
local r = {}
for k, v in ipairs{...} do
r = v.new(r)
end
return r
end
Sequence = {}
SequenceMetatable = { __index = Sequence }
setmetatable(Sequence, {
__call = function(cls, ...)
return cls.new(...)
end
})
function Sequence.new(name)
return setmetatable({name = 'sequence-' .. name}, SequenceMetatable)
end
function Sequence:next()
local currentSequence = system.getItem(self.name)
if (nil == currentSequence) then
currentSequence = 0
end
local nextSequence = currentSequence + 1
system.setItem(self.name, nextSequence)
return nextSequence;
end
--- mint.lua
MintService = { }
MintServiceMetatable = { __index = MintService }
setmetatable(MintService, {
__call = function(cls, ...)
return cls.new(...)
end
})
function MintService.new(parent)
return setmetatable({ parent = parent },
MintServiceMetatable)
end
function MintService:totalAmount(assetSymbol)
if AssetTypes.exists(assetSymbol) then
local mintInfo = system.getItem('mint-' .. assetSymbol)
return mintInfo.amount or -1
else
return -1
end
end
function MintService:issue(assetSymbol, amount)
amount = tonumber(amount)
assert(0 < amount)
if not AssetTypes.exists(assetSymbol) then
AssetTypes.register(assetSymbol)
end
local issuer = system.getSender()
local mintInfo = system.getItem('mint-' .. assetSymbol) or { issuer = issuer, amount = 0 }
assert(mintInfo.issuer == issuer, 'no authority')
mintInfo.amount = M.add(mintInfo.amount, amount)
system.setItem('mint-' .. assetSymbol, mintInfo)
if self.parent and self.parent.balanceService then
self.parent.balanceService:receiveFromExternal(issuer, assetSymbol, amount)
end
end
MintServiceComponent = {}
MintServiceComponentMetatable = { __index = MintServiceComponent }
setmetatable(MintServiceComponent, {
__call = function(cls, ...)
return cls.new(...)
end
})
function MintServiceComponent.new(o)
local data = o or {}
data.mintService = MintService(data)
return setmetatable(data, MintServiceMetatable)
end
--- balance.lua
BalanceService = { }
BalanceServiceMetatable = { __index = BalanceService }
setmetatable(BalanceService, {
__call = function(cls, ...)
return cls.new(...)
end
})
function BalanceService.new(parent)
return setmetatable({ parent = parent }, BalanceServiceMetatable)
end
function BalanceService:getAmount(address, assetSymbol)
assert(nil ~= address)
local account = system.getItem('account-' .. address)
if nil == account then
return 0
else
return account[assetSymbol] or 0
end
end
function BalanceService:receiveFromExternal(receiverAddress, assetSymbol, amount)
amount = tonumber(amount)
local receiverAccount = system.getItem('account-' .. receiverAddress) or { balance = 0 }
assert(0 < amount)
assert(nil ~= receiverAddress)
local key = assetSymbol
receiverAccount[key] = M.add(receiverAccount[key] or 0, amount)
system.setItem('account-' .. receiverAddress, receiverAccount)
if nil ~= self.parent and nil ~= self.parent.historyService then
local tx = Transaction(2, nil, receiverAddress, assetSymbol, amount)
self.parent.historyService:record(tx)
end
end
function BalanceService:transfer(receiverAddress, assetSymbol, amount)
amount = tonumber(amount)
local senderAddress = system.getSender()
local senderAccount = system.getItem('account-' .. senderAddress)
local receiverAccount = system.getItem('account-' .. receiverAddress) or { balance = 0 }
assert(0 < amount)
assert(nil ~= receiverAddress)
assert(nil ~= senderAccount)
local key = assetSymbol
assert(amount <= senderAccount[key], 'insufficient balance')
senderAccount[key] = M.sub(senderAccount[key] or 0, amount)
receiverAccount[key] = M.add(receiverAccount[key] or 0, amount)
system.setItem('account-' .. senderAddress, senderAccount)
system.setItem('account-' .. receiverAddress, receiverAccount)
if nil ~= self.parent and nil ~= self.parent.historyService then
local tx = Transaction(1, senderAddress, receiverAddress, assetSymbol, amount)
self.parent.historyService:record(tx)
end
end
BalanceServiceComponent = {}
BalanceServiceComponentMetatable = { __index = BalanceServiceMetatable }
setmetatable(BalanceServiceComponent, {
__call = function(cls, ...)
return cls.new(...)
end
})
function BalanceServiceComponent.new(o)
local data = o or {}
data.balanceService = BalanceService(data)
return setmetatable(data, BalanceServiceComponentMetatable)
end
Transaction = { }
TransactionMetatable = { __index = Transaction }
setmetatable(Transaction, {
__call = function(cls, ...)
return cls.new(...)
end
})
function Transaction.new(type, sender, receiver, assetType, amount)
setmetatable({
type = type,
sender = sender,
receiver = receiver,
assetType = assetType,
amount = amount
}, TransactionMetatable)
end
HistoryService = {}
HistoryServiceMetatable = { __index = HistoryService }
setmetatable(HistoryService, {
__call = function(cls, ...)
return cls.new(...)
end
})
function HistoryService.new(parent)
return setmetatable(
{ parent = parent, sequence = Sequence('history') },
HistoryServiceMetatable)
end
function HistoryService:record(transaction)
system.setItem('history-' .. self.sequence:next(), transaction)
end
HistoryServiceComponent = {}
HistoryServiceComponentMetatable = { __index = HistoryServiceComponent }
setmetatable(HistoryServiceComponent, {
__call = function(cls, ...)
return cls.new(...)
end
})
function HistoryServiceComponent.new(o)
local data = o or {}
data.historyService = HistoryService(data)
return setmetatable(data, HistoryServiceComponentMetatable)
end
--- asset.lua
AssetType = { }
AssetTypeMetatable = { __index = AssetType }
setmetatable(AssetType, {
__call = function(cls, ...)
return cls.new(...)
end
})
AssetTypes = {}
function AssetTypes.exists(symbol)
return nil ~= system.getItem('symbol-' .. symbol)
end
function AssetTypes.register(symbol)
assert(not AssetTypes.exists(symbol))
system.setItem('symbol-' .. symbol, symbol)
end
local tokenSystem = Mixer(MintServiceComponent, BalanceServiceComponent, HistoryServiceComponent)
function constructor()
tokenSystem.mintService:issue('bds1-token', 300000000)
end
function transfer(receiver, amount)
tokenSystem.balanceService:transfer(receiver, 'bds1-token', amount)
end
function getAmount(address)
return tokenSystem.balanceService:getAmount(address, 'bds1-token')
end
abi.register(transfer, getAmount)
```