Giters

mgpai22 / comet-lottery

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Comet Lottery Off-Chain Node

Smart contracts on Ergo Blockchain are simple compared to Ethereum as they do not self-execute. Instead, Ergo Contracts require external programs or bots to interact with them in order to process transactions.

This is in contrast to Ethereum's virtual machine (EVM), which handles these tasks automatically, coming at the cost of increased complexity and resource consumption on the blockchain.

Code Structure

  • Akka is the backbone that repeatedly checks api and calls functions
  • Running the jar starts the main function in app.Main
  • mint.akkaFunctions contains all the scenarios which either generate contracts, mint tickets, or process winner
  • mint.akkaFunctions know which function to called based on the data in lotteryConf.json
  • smart contracts are here

Lottery Structure

Initialization

  • Singleton and contracts are generated by master node/bot
  • All corressponding information is written to lotteryConf.json

Minting

  • Buyers send funds to the proxy contract

    • The output box must have a sigmaProp of the address where they want to receive the ticket in R4
    • Important that non-devs use frontend so they don't accidently loose funds as you cannot just directly send funds to the contract
    • If funds/boxes in proxy are not picked up by bot, they can be refunded to the address specified in R4
    • This refund must be done via frontend as the buyer needs to sign the transaction

  • Bot sends ticket to buyer

Winner Selection

  • After timestamp is reached, (specified by timestamp in lotteryConf.json) a random number determines which ticket number is the "winner"

  • At least seven tickets must be bought for anything to happen or else there will not be enough ERG to pay for tx fees

  • This ticket has a chance specified in serviceOwner.json to actually win the lottery funds

  • If the chance is met, and the ticket wins

    • 90% of the pool funds goes to winner
    • 10% of the pool funds goes to a distribution address
    • singleton token is burned
    • We now go back to initialization

  • If the chance is not met, there is no winner and lottery moves to new version

    • The funds gets transferred back to pool (collection contract)
    • version increments
    • old tickets purchased are ineligible to be selected
    • timestamp increases by the time specified in serviceOwner.json
    • contracts still stay the same
    • We now go back to minting

Contract Flow Diagram

  • will be updated soon

Deployment

  • It is recommended to use the jar to run the node

    • Jar can be downloaded from the lastest release
    • Jar can be built by running sbt clean assembly in the same directory as build.sbt

  • serviceConf.json must be filled out correctly before running jar

Master Bot

  • Highly recommended to run master bot with corresponding python api

  • master bot is started with java -jar comet-lottery-1.1.0.jar

  • once you stop your master node, there is no guarantee that the lottery will stop since other people may be running follower nodes. They will only copy your new contracts if their lottery ends or if the runner mannually sets timeStamp to "null"

Follower Bot

  • This bot requires a master api in order to automatically pull in contracts

  • This bot ensures that master has generated new contracts and that one ticket has been processed (firstTime in lotteryConf.json should be set to false)

    • Only if these two conditions are met, the new contracts are pulled in

  • Follower bot is started with java -jar comet-lottery-1.1.0.jar --follow serviceUrl lotteryUrl

  • Follower will only use master api again if its local lottery has ended. Therefore, there is a possibility that master may have abandoned lottery. In this case, if you want to sync to master contracts again, stop the bot and set timeStamp in lotteryConf.json to "null".

Config Parameters

  • There are two files which drive the bot
    • lotteryConf.json
    • serviceOwner.json

lotteryConf.json

  • Note it is important not to manually tamper with this file, the only thing that can be done manually is setting timeStamp to "null"

  • version

    • Helps lottery keep track of version

  • initTransaction

    • Each time a new version is created (loser selected) the first transaction is recorded, this is important since is is used to find the winning ticket by traversing through all the spent txIds

  • distributionAddress

    • This address will get 10 % of the funds from the pool

  • firstTime

    • The very first time the lottery is created/generated this is set to true.
    • This is important since boxes are found with different api requests during the first time

  • timeStamp

    • the actual time stamp when winner can be drawn
    • bot knows to start new lottery only if this is set to "null"
    • set to "null" if you want to force recreate a new lottery where old contracts will be overwritten

  • ticketContract

    • contains contract address, singleton id, and inital box id

  • collectionContract

    • contains contract address, and inital box id

  • proxyContract

    • contains contract address

  • winnerSelectionContract

    • contains contract address

  • winningNFT

    • id of the winner nft/ticket when selected

  • winningAddress

    • address of the winner stored when found

serviceOwner.json

  • ownerMnemonic

    • This is required to generate and process contracts
    • Must have at least have one comet per new lottery so its reccommended to have a reasonable amount of tokens
    • Any rewards for processing transactions will be sent to this mnemonic's respective address

  • ownerMnemonicPw

    • This is specfically for any passwords that need to be used with your mnemonic
    • Most wallets don't support this
    • Node wallets prominently have this feature
    • This is NOT your wallet password
    • Leave an empty string if no password

  • cometId

    • token id of comet token
    • Can be any token
    • If adding any other token be mindful of how decimals of the tokens
    • cometId is 0cd8c9f416e5b1ca9f986a7f10a84191dfb85941619e49e53c0dc30ebf83324b

  • cometTicketPrice

    • Price per ticket in comet
    • If a token with a different number of decimal places is used be mindful of that
      • Neta has six decimal places
      • So if Neta is the token, 100 ticket price should be 100 * 10**6 =>100000000

  • winnerChance

    • Everytime its time to draw a winner, someone will be selected, however, they will only have a winnerChance % of winning anything
    • For 10 % chance you would put 10

  • timeBeforeUnlockMS

    • Lottery will allow a winner to be selected after timeBeforeUnlockMS (remember this is in milliseconds)
    • Once someone becomes a loser by failing the chance of winning, a new lottery version is created in which a winner will again be selected after timeBeforeUnlockMS
    • If you want a winner to be selected everyday you would put 86400000

  • distributionAddress

    • This address will get 10 % of the funds from the pool

  • singletonName

    • A singleton token (unique type of token in which only one unit exists) helps keep track of the TicketContract Box
    • It also helps identify the lottery in the api (check out comet-lottery-docker)
    • Name can be anything

  • singletonDesc

    • Description for the token

  • ticketName

    • Check lottery ticket will have this name
    • Program will automatically will increment version and count
    • If ticket is named comet lottery ticket, the first ticket would be named comet lottery ticket 1 v1

  • ticketDesc

    • Description for the ticket

  • oracleNFT

    • An oracleNFT changes its boxId every six blocks
    • This boxId is queried with the NFT and it is used to generate a random number in range of all the tickets bought
    • This can be set to either
      • Eth/USD
        • 002693cd6c3dc7c156240dd1c7370e50c4d1f84a752c2f74d93a20cc22c2899d
      • Erg/USD
        • 011d3364de07e5a26f0c4eef0852cddb387039a921b7154ef3cab22c6eda887f

  • nodeUrl

    • ergo node is important as txns gets submitted through it
    • If you use your own local node you have a better chance of submitting a transaction earlier and earning rewards
    • You can use this as a node http://213.239.193.208:9053
    • Go here to find other nodes, be sure to select one with openRestApi: true
    • If you want to use https://ergonode-api-uy.ergohost.io (note this is a url rather than an ip) for example, you can directly put that in the config without any ports
    • Be sure to look at this if you want to run your node

  • apiUrl

    • explorer api is heavily used to get information about transactions
    • use https://api.ergoplatform.com as it is the most reliable
      • others include
        • https://tn-ergo-explorer.anetabtc.io
        • https://ergo-explorer.tosidrop.io
        • these are not as reliable but could be useful for backup incase the main one is under stress

About

Languages

Language:Scala 68.1%Language:JavaScript 12.0%Language:HTML 10.9%Language:Java 5.2%Language:CSS 2.5%Language:Python 1.0%Language:Dockerfile 0.2%