Skip to content

liquidity-network/nocust-hub

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

3 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

NOCUST-server

This will guide you through the server's code.

For detailed endpoint documentation deploy a local development operator using nocust-ensemble and check Local API documentation.

Deployment

Clone the repo and its submodules

git clone --recurse-submodules https://github.com/liquidity-network/nocust-server.git

Developpment hub

This will create a local POA blockchain running with Parity, deploy the contracts, and start a NOCUST hub.

./run.sh

Production hub

This is to operate a hub on public an already existing Blockchain (Rinkeby, Kovan, ETH mainnet, etc..). This will require to have a nocust smart-contract manually deployed, See https://github.com/liquidity-network/just-deploy/. You will need to create an .env file at the root of the repo with at least the following variables:

HUB_OWNER_ACCOUNT_ADDRESS=0xXXXXXX
HUB_OWNER_ACCOUNT_KEY=XXXXXXXX
HUB_LQD_CONTRACT_ADDRESS=0xXXXXXXXX
HUB_LQD_CONTRACT_CONFIRMATIONS=20
SLA_TOKEN_ADDRESS=0xXXXXXXXX
HUB_ETHEREUM_NODE_URL=YYYYYYY
  • HUB_OWNER_ACCOUNT_ADDRESS NOCUST hub Operator address with 0x
  • HUB_OWNER_ACCOUNT_KEY Private key of the operator without 0x !! Very sensitve !!
  • HUB_LQD_CONTRACT_ADDRESS NOCUST contract address
  • HUB_LQD_CONTRACT_CONFIRMATIONS amount of blocks, used for confirmation of deposits, withdrawals, etc..
  • HUB_ETHEREUM_NODE_URL Http(s) RPC endpoint URL (i.g Infura)
  • HUB_ETHEREUM_NETWORK_IS_POA if in local developement you are using POA-networks (Like Rinkeby), then this flag should be set as True. For ETH mainnet use False

To run the production hub, simply do:

./run.sh prod

Contract deployment

deploy_contract.sh will ask you about node url, owner address and private key. After that it will create docker container for deployment and return to you address of deployed contract. This address you should put into .env file.

Contract deployment

deploy_contract.sh will ask you about node url, owner address and private key. After that it will create docker container for deployment and return to you address of deployed contract. This address you should put into .env file.

Optional notification

  • NOTIFICATION_HOOK_URL should be slack notification url, if you want to use notification system
  • SERVER_NAME if you have a several servers, but same notification slack channel, please set this variable

Contract deployment

deploy_contract.sh will ask you about node url, owner address and private key. After that it will create docker container for deployment and return to you address of deployed contract. This address you should put into .env file.

Optional notification

  • NOTIFICATION_HOOK_URL should be slack notification url, if you want to use notification system
  • SERVER_NAME if you have a several servers, but same notification slack channel, please set this variable

Server Architechture

The server spans 6 different processes, each has it's own function:

  1. Server
  2. Scheduler
  3. Accounting
  4. Audit
  5. Chain
  6. Verifier

Server

  • Started using runserver.sh
  • Handles HTTP & Websocket connections
  • Handles synchronous business logic
    • initial swap validation & confirmation found in swapper
    • transfer validation & confirmation found in transactor
    • admission validation found in admission

Scheduler

Accounting

Audit

Chain

  • Started using celeryworker_chain.sh
  • Handle parsing blocks and other tasks requiring parallelism found in contractor tasks

Verifier

  • Started using celeryworker_verifier.sh
  • Handle tasks involving communication with the smart contract found in contractor tasks
    • synchornize contract state
    • respond to challenges
    • confirm withdrawals
    • write queued transactions to the blockchain

Module List

The server is broken down to 12 functions, logic is grouped into the following 12 modules:

  1. Operator API
  2. Admission
  3. Analytics
  4. Auditor
  5. Contractor
  6. Heartbeat
  7. Ledger
  8. Leveller
  9. Swapper
  10. Synchronizer
  11. Terms of Service
  12. Transactor

Operator_api

Main Django app module, contains all common server configurations and utilities.

  • periodic-task schedule
  • alert mail client configuration
  • logging configuration
  • all app settings (controlled by environmental variables)
  • base mutex data model
  • base merkle-tree data structures
  • crypto utilities
  • merkle tree hash cache
  • custom swagger schema generation configurations
  • optional performance profiling endpoints
  • auto-generated swagger docs
  • NOCUST simulations (simulate all NOCUST client events & operator processes)
Name Description
BulkManager utility model used to batch database updates
CleanModel utility model used to wrap other models with https://docs.djangoproject.com/en/2.2/ref/models/instances/#django.db.models.Model.full_clean
ErrorCode utility model containing all validation error code constants
ReadWriteLock utility model to wrap other models with a redis based parallel read, single write lock
MutexModel utility model to wrap other models with a redis based mutex
MockModel utility model used to mock arbitrary data models defined at runtime

Admission

All registration endpoints and registration confirmation background tasks.

Analytics

Endpoints returning multiple usage metrics eg. transactions, deposits, withdrawals etc.. (you can learn more about this by checking the swagger documentation).

Auditor

Contains endpoints used to audit the off-chain ledger, as well as all user-facing data serializers.

  • user-facing data serializers
  • endpoints to fetch off-chain ledger data

Contractor

Contains abstraction layers around the NOCUST smart-contract and everything related to syncing state with the blockchain.

  • smart-contract ABI
  • smart-contract python interface
  • smart-contract event interpreters
  • smart-contract transaction models (including retries)
  • block state parsing

Models

Name Description
ChallengeEntry on-chain ledger challenge record
ContractLedgerState on-chain ledger state for every token including number of withdrawals, deposits and total balance
ContractParameters on-chain ledger parameters including genesis block, blocks per eon and challenge cost
ContractState on-chain ledger state snapshot per block, keeps track of whether a checkpoint was submitted or missed, in addition to the number of live challenges
EthereumTransactionAttempt on-chain ethereum transaction submission attempt
EthereumTransaction on-chain ethereym transaction to be submitted

Heartbeat

Bundles together tasks that run periodically, the tasks themselves are defined in other modules.

Ledger

Contains off-chain ledger models and all the logic required to construct the off-chain ledger (still has some deprecated logic related to active transfers).

  • off-chain ledger data models
  • off-chain ledger database integrity constraints
  • off-chain ledger wallet state construction logic (wallet-transfer context)

Models

Name Description
ActiveState off-chain wallet's active state including monotonically increasing spend and gained amounts in addition to the active transaction set hash
Blacklist wallets forbidden from admitting to the ledger
BlockchainTransaction base model used in Deposit, WithdrawalRequest and Withdrawal models
Deposit on-chain deposit
WithdrawalRequest on-chain withdrawal request
Withdrawal on-chain confirmed withdrawal
Challenge on-chain challenge includes a flag to indicate whether this challenge was rebuted
ExclusiveBalanceAllotment off-chain wallet's allocated balance, including latest merkle proof data, active state, left and righ balance offsets
Matching off-chain order-pair matching information, including time when the matching happened and the filled amounts of both orders
MinimumAvailableBalance off-chain commitment made by the wallet's owner to not withdraw more than a specific minimum available amount
RootCommitment off-chain ledger's merkle root
Signature off-chain wallet signature
TokenCommitment off-chain token tree commitment
TokenPair trading pair whitelist
Token token model, including address and name
Transaction base transaction model used in Transfer
Transfer off-chain transfer & swap model (single table inheritance), including busines logic to read and change transaction's state as well as some data caching fields
Wallet off-chain wallet model, including some business logic to generate and validate signatures

Leveller

Endpoints used to subscribe to the operator's service level agreement.

Models

Name Description
Agreement service level agreement subscription

Swapper

Endpoints used to make, match and manage swaps.

  • swap endpoints
  • swap matching algorithm
  • multi-eon swap support logic

Synchronizer

Websockets notification implementation and docs.

TOS

Endpoints used to sign the operator's terms of service, handles updates to the terms of service automatically.

Models

Name Description
TOSConfig terms of service configuration, including terms of service and privacy policy digests, a new record is added automatically whenever the terms of service is updated
TOSSignature specific wallet's signature of a given terms of service config

Transactor

Endpoints used to make transactions.

Disclaimer

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

About

Open source NOCUST hub server repo

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published