# Design document of ledger module

# Overall description

# 1.1 Module Overview

# 1.1.1 Why do you have a "book module"?

The ledger module is the data hub of the blockchain. The balances and transactions of all accounts are saved in the ledger module. A network-wide account book is saved on each network node to ensure complete, open and transparent data, while ensuring that data cannot be tampered and traceable.

# 1.1.2 What should be done in the "book module"

Provide data support for assembly transactions, mainly accounting and auditing, verify the legality of the transaction, such as: whether there is sufficient balance, whether to repeat payment (double flower)

# 1.1.3 Positioning of the "book module" in the system

The ledger module is the data hub, which stores the result data of all existing transactions in the system. It does not depend on any business modules, and other modules depend on it as needed.

# 1.1.4 Explanation of terms in "book module"

• The random number of the transaction (nonce, a 32-bit hash value)
  • nonce: A scalar value equal to the number of transactions sent at this address, which will be included in every transaction initiated by the user.
  • Each transaction in the account needs to save the nonce (hash) of the previous transaction
  • Strictly speaking, a nonce is an attribute of the originating address (it only makes sense in the context of the sending address).However, the nonce is not explicitly stored in the blockchain as part of the account status.
  • The nonce value is also used to prevent incorrect calculation of account balances.For example, suppose an account has 10 NULS balances and signs two transactions, all of which cost 6 NULS with nonce 1 and nonce 2, respectively.Which of these two transactions is valid? In a blockchain distributed system, nodes may receive transactions out of order.Nonce forces transactions of any address to be processed in order, regardless of the interval, regardless of the order in which the nodes receive.This way, all nodes will calculate the same balance.Payments for 6 Ethereum will be processed successfully and the account balance will be reduced to 4 ether.Whenever it is received, all nodes consider it invalid with a transaction with nonce 2.If a node receives a nonce 2 transaction first, it will hold it, but will not verify it until it receives and processes the nonce 1 transaction.
  • Use nonce to ensure that all nodes calculate the same balance and sort the transactions correctly, which is equivalent to the mechanism used in Bitcoin to prevent "double payment".However, because Ethereum tracks account balances and does not track individual coins separately (called UTXO in Bitcoin), "double payments" only occur when the account balance is incorrectly calculated.The nonce mechanism can prevent this from happening.

# 1.2 Architecture

The core of the books is asset management and bookkeeping management.

# Functional design

# 2.1 Functional Architecture

# 2.2 Module Service

# 2.2.1 System Service of the Book Module

The interface of rpc provided by the ledger module. For detailed interface, please refer to the interface design section.

# 2.2.2 Modifying system operating parameters

Only rely on the core system, the core system can start, stop, modify parameters, etc. of the event module system,

# 2.3 Module internal function

# 2.3.1 Hot (online) transaction processing

Module internal work mainly includes asset management, obtaining account address balance and nonce, and verifying transaction coinData.

• asset Management
  • Total assets of the account
  • Available assets
  • Freeze assets. For locked assets, separate record and locked asset information, including chain id, asset id, asset amount, lock time, lock height, etc.
  • In the asset unlocking process, when the user's locked asset time or height reaches the unlocking condition, the account will unlock the asset information, accumulate the available balance, and delete the asset lock record of the local data.
  • Multi-asset situation, need to join chainId.
• Get account address balance and nonce
  • Get account address balance
  • Get the account address nonce (the nonce is the last eight digits of a transaction hash value, meaning that the nonce of the first transaction is 0. Each future transaction of the account will contain the nonce value of the previous transaction)
• Verify the transaction
  • Double flower verification (nonce mechanism prevents double payment)
  • Transaction creator verification, verifying that the issuer of the transaction has sufficient balance to verify that the nonce of the transaction creator is legal
  • Continuous transaction verification
• Function Interface Management (rpc)
  • rpc interface for use by other modules

# 2.3.2 Cold (offline) transaction processing

A cold wallet is an unconnected wallet, also called an offline wallet.A hot wallet is a wallet that keeps online, that is, an online wallet.Cold wallets are not more secure than hot wallets.

Since the cold wallet only signs the transaction information, the signed hex string is transmitted to the server through the hot wallet, and then the server performs unified transaction processing, so the client needs to perform the offline signature function. The offline transaction system maintains the storage information of the nonce. After using a nonce, the nonce is saved in the business system.

Most offline transactions are handled by the exchange itself, we need to store the account data of the entire network account

# 2.4 Bookkeeping Process

# 2.4.1 Transfer Transaction Process

• User enters the address of the transfer and the transferred address and the transferred amount
• The system signs the transfer information by the private key of the transferred address (used to prove that the transaction was actually initiated by me)
• The system verifies the transaction information
  • Balance verification
  • Fee verification
  • nonce continuity verification
  • Signature and input account verification
• Put this transaction into the local TxPool (that is, the account unconfirmed trading pool)
• Broadcast transaction information to other nodes
• Packing blocks, verifying blocks
• Confirm transaction
  • Update the balance of all accounts related to (transfer or transfer)
  • Update the nonce corresponding to the account asset

# 2.4.2 Ordinary transaction process (reference example)

# 2.4.3 Transaction Verification Process

# Interface Design

# 3.1 Module core interaction interface

# 3.1.1 Get account balance

cmd: getBalance

# Parameter Description (request)

{
   
    "chainId":5,
    "address":"0x407d73d8a49eeb85d32cf465507dd71d507100c1",
    "assetChainId":34,
    "assetId":5,
}

# Return value description (response)

{ 
       "available": "10000000000",
       "freeze": "200000000",
       "total": "12000000000"
}

Description: 1NULS=10^8Na

# 3.1.2 Get the current account nonce value

cmd: getNonce

# Parameter Description (request)

{
   
    "chainId":5,
    "address":"0x407d73d8a49eeb85d32cf465507dd71d507100c1",
    "assetChainId":34,
    "assetId":5,
}

# Return value description (response)

{
   "nonce":"xxxxxxxxxxx"，
   "nonceType":1
}

# 3.1.3 Obtaining the balance and nonce value

cmd: getBalanceNonce

# Parameter Description (request)

{
   
    "chainId":5,
    "address":"0x407d73d8a49eeb85d32cf465507dd71d507100c1",
    "assetChainId":"34",
    "assetId":"5",
}

# Return value description: (response)

{
    "available": "10000000000",
    "nonce": "xxxxx"
}

# 3.1.4 Verifying coinData

cmd: verifyCoinData

# Parameter Description (request)

{
    "chainId": 458,
    "txHex": "xxxxxxxx"
}

# Return value description: (response)

In the case of failure, the fail error code is returned uniformly.
Successfully:
{
    "orphan":true
}

# 3.1.5 Batch verification notice

cmd: bathValidateBegin

# Parameter Description (request)

{
     "chainId": 21
}

# Return value description: (response)

{
    "value":1
}

# 3.1.6 Submitting unconfirmed transactions

cmd: commitUnconfirmedTx

# Parameter Description (request)

{
     "chainId": 21,
     "txHex": "xxxxxxxx"
}

# Return value description: (response)

In the case of failure, the fail error code is returned uniformly.

Successfully:
{
    "orphan":true
}

# 3.1.7 Submitting unconfirmed transactions in bulk

cmd: commitBatchUnconfirmedTxs

# Parameter Description (request)

{
     "chainId": 21,
     "txList": "[xxxxxxxx，yyyyyyyyy]"
}

# Return value description: (response)

{
    "orphan":"[xxxxxxxx，yyyyyyyyy]"，
    "fail":"[aaaaaaaa，bbbbbbbbb]"
}

# 3.1.8 Submitting block transactions

cmd: commitBlockTxs

# Parameter Description (request)

{
     "chainId": 21,
     "txHex": "[xxxxxxxx,yyyyyyyy]",
     "blockHeight": 25
}

# Return value description: (response)

{
    "value":true
}

# 3.1.9 Rolling back unconfirmed transactions

cmd: rollBackUnconfirmTx

# Parameter Description (request)

{
     "chainId": 21,
     "txHex": "xxxxxxxx"
}

# Return value description: (response)

{
    "value":1
}

# 3.1.10 Rollback block trading

cmd: rollBackBlockTxs

# Parameter Description (request)

{
     "chainId": 21,
     "blockHeight": 25
}

# Return value description: (response)

{
    "value":1
}

# 3.1.11 Entire block check

cmd: blockValidate

# Parameter Description (request)

{
     "chainId": 21,
     "txList": "[xxxxxxxx，yyyyyyyyy]",
     "blockHeight":20
}

# Return value description: (response)

{
    "value":true
}

# 3.2 Other interfaces

# 3.2.1 Obtain asset information based on asset id

cmd: getAsset

# Parameter Description (request)

{
  "chainId": 5,
  "assetChainId": 12,
  "assetId": 41
}

# Return value description (response)

{
    "chainId": 5,
    "assetChainId": 12,
    "assetId": 41,
    "balance" : {
      "available": "10000000000",
      "freeze": "200000000",
      "total": "12000000000"
    }
}

# Description of the event

does not depend on any events

# Agreement

# 5.1 Network Communication Protocol

no

# 5.2 Trading Agreement

no

# Module Configuration

# 6.1 Configuration Instructions

# 6.2 Module Dependencies

• Kernel module

  • Module registration

  • Module logout

  • Module status escalation (heartbeat)

  • Service interface data acquisition and timing update

• Network module

# Java-specific design

Core object class definition, storing data structures, ...

# Supplementary content

# References Literature

• Proficient in Ethereum - Chapter 7 Transaction