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.
Clone the repo and its submodules
git clone --recurse-submodules https://github.com/liquidity-network/nocust-server.git
This will create a local POA blockchain running with Parity, deploy the contracts, and start a NOCUST hub.
./run.sh
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_ADDRESSNOCUST hub Operator address with0xHUB_OWNER_ACCOUNT_KEYPrivate key of the operator without0x!! Very sensitve !!HUB_LQD_CONTRACT_ADDRESSNOCUST contract addressHUB_LQD_CONTRACT_CONFIRMATIONSamount of blocks, used for confirmation of deposits, withdrawals, etc..HUB_ETHEREUM_NODE_URLHttp(s) RPC endpoint URL (i.g Infura)HUB_ETHEREUM_NETWORK_IS_POAif in local developement you are using POA-networks (Like Rinkeby), then this flag should be set asTrue. For ETH mainnet useFalse
To run the production hub, simply do:
./run.sh prod
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.
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.
NOTIFICATION_HOOK_URLshould be slack notification url, if you want to use notification systemSERVER_NAMEif you have a several servers, but same notification slack channel, please set this variable
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.
NOTIFICATION_HOOK_URLshould be slack notification url, if you want to use notification systemSERVER_NAMEif you have a several servers, but same notification slack channel, please set this variable
The server spans 6 different processes, each has it's own function:
- 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
- Started using
celerybeat.sh - Handle periodic task scheduling
- schedule found in operator API's celery config file
- Started using
celeryworker_accounting.sh - Handle off-chain ledger accounting, off-chain confirmation and integrity checks
- admission confirmation found in admission tasks
- slash bad withdrawals found in contractor tasks
- multi-eon swap confirmation found in swapper tasks
- swap matching found in swapper matcher
- create checkpoint found in ledger tasks
- Started using
celeryworker_audit.sh - Handle sending out websocket notifications found in auditor tasks and synchronizer tasks
- Handle automatic terms of service update found in tos tasks
- Started using
celeryworker_chain.sh - Handle parsing blocks and other tasks requiring parallelism found in contractor tasks
- 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
The server is broken down to 12 functions, logic is grouped into the following 12 modules:
- Operator API
- Admission
- Analytics
- Auditor
- Contractor
- Heartbeat
- Ledger
- Leveller
- Swapper
- Synchronizer
- Terms of Service
- Transactor
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 |
All registration endpoints and registration confirmation background tasks.
Endpoints returning multiple usage metrics eg. transactions, deposits, withdrawals etc.. (you can learn more about this by checking the swagger documentation).
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
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
| 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 |
Bundles together tasks that run periodically, the tasks themselves are defined in other modules.
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)
| 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 |
Endpoints used to subscribe to the operator's service level agreement.
| Name | Description |
|---|---|
| Agreement | service level agreement subscription |
Endpoints used to make, match and manage swaps.
- swap endpoints
- swap matching algorithm
- multi-eon swap support logic
Websockets notification implementation and docs.
Endpoints used to sign the operator's terms of service, handles updates to the terms of service automatically.
| 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 |
Endpoints used to make transactions.
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.