# Table of Contents - [Unknown](#unknown) - [Drosera · Ethereum Evolved – Docs](#drosera-ethereum-evolved-docs) - [Getting Started – Docs](#getting-started-docs) - [Introduction – Docs](#introduction-docs) - [Installation – Docs](#installation-docs) - [Litepaper – Docs](#litepaper-docs) - [Use Cases – Docs](#use-cases-docs) - [Updating a Trap – Docs](#updating-a-trap-docs) - [Boosting a Trap – Docs](#boosting-a-trap-docs) - [Hydrating a Trap – Docs](#hydrating-a-trap-docs) - [Creating a Trap – Docs](#creating-a-trap-docs) - [Drosera CLI – Docs](#drosera-cli-docs) - [Dryrunning a Trap – Docs](#dryrunning-a-trap-docs) - [Kicking an Operator – Docs](#kicking-an-operator-docs) - [Setting Bloomboost Percentage – Docs](#setting-bloomboost-percentage-docs) - [Recover your drosera.toml File – Docs](#recover-your-drosera-toml-file-docs) - [Getting Liveness Data – Docs](#getting-liveness-data-docs) - [Registration – Docs](#registration-docs) - [Run the Node – Docs](#run-the-node-docs) - [Executing Traps – Docs](#executing-traps-docs) - [Testnet Guide – Docs](#testnet-guide-docs) - [Private Traps – Docs](#private-traps-docs) - [Monitoring – Docs](#monitoring-docs) - [Run on Railway – Docs](#run-on-railway-docs) - [Run with Docker – Docs](#run-with-docker-docs) - [Run on a VPS – Docs](#run-on-a-vps-docs) - [Deployments – Docs](#deployments-docs) --- # Unknown Drosera TheSecurityAutomationLayer SamuelGlenn JacobVeal FernandoD.Reyes,Jr. RichardMalone Abstract Complexsmartcontractsandmulti-contractprotocolsposesignificantriskstousersand theintegrityoftheecosystem.Whileindividualcontractscanbeformallyverified,itbecomes practicallyimpossiblewhendealingwithmodularmulti-protocolsystems.WeproposeDrosera, adecentralizedsecurityautomationlayeronEthereum,toreducetheserisks.Droseraisasetof smartcontractsthatallowoperatorstoperformzero-knowledgeincidentresponserolesfor protocols.ThismeansthatoperatorsactonthesecurityintentsdefinedbyProtocols.Security infrastructureisoffloadedtoanetworkofoperators,whichreducesgascostsforusers,increases security,anddecreasesincidentresponsetime.Operatorscantriggeremergencyresponse mechanismstoalertthecommunityandmitigatedamage.Theseoperatorshaveadditional slashingconditionsimposedonthemiftheyperformmaliciousorincorrectattestations.Rather thancreatinganewtrustnetwork,DroseraaimstoleverageEthereum’sexistingtrustnetworkto bolsteritscrypto-economicsecurity. 1.TheProblem:RiskMitigation Decentralizednetworkshaverevolutionizedthewaywemanagedigitalassets.In2022,nearly $3.8billionwassiphonedfromtheDeFiecosystemthroughvarioussmartcontractcompromises \[1\].Compromisedprotocolsremainasignificantchallengebecauseofrelianceoninsufficient securitycoverageandpoorincidentresponseplans.Ethereumneedsanativesecurity complementtomitigatetheserisks.Droseraaimstocreateaframeworkthatfacilitates innovationandreal-worldadvancementsintheseareas. 1.1InsufficientSecurityCoverage InEVMsmartcontracts,advancedvalidationlogicpresentsadouble-edgedsword. Protocolsmustnavigatethefinelinebetweenimplementingcomprehensivevalidation checksandensuringusersaren'tburdenedwithhighgascostsincurredintransactions. Thisissueincreasestheriskofacompromisetomaintainuseraccessibility.As Ethereum'sgaspricesremainvolatile,implementingcomplexvalidationcheckscandeter usersbecauseofincreasedtransactioncosts.Theoretically,formalverificationmethods couldassureprotocolcorrectnessandminimizetheneedforintricatevalidationlogic\[2\]. However,itscost,complexity,andtime-consumingnaturehinderitsadoptionandrender itfundamentallyimpracticalforcomplexmodularsystems.Theprotocolownersbearthe burdenofround-the-clockincidentresponse,astrategythatisinvariablytoolateto mitigatedamage,makingadditionalsecuritysupplementsindispensable. 1.2RobustSecurityRequiresAuditingandMonitoring Auditingremainsaleadingsecuritymeasurethatprotocolsemploy.However,the relianceonauditorshasrisks.Datavalidationflaws,whicharehighlycommonand hazardous,comprise36%ofsmartcontractfindings,andaccesscontrolissuesaccount foranother10%.Thesevulnerabilities,ifexploited,canleadtosignificantdamage \[3\] . Duetothepotentialforhumanerror,protocolscannotfullytrusttheauditor'scontract assessment.Thisrealityunderlinestheimportanceofadditionalprotectivemeasures. Despitethepotentialofautomatedtools,only26%ofallfindingscouldlikelybedetected usingfeasiblestaticapproaches,and37%usingdynamicmethods.Evenconsideringonly theworsthigh-lowfindings,statictoolsarelesseffectivethandynamicones(33%vs. 63%) \[3\] .Therefore,itwouldbeprudenttocomplementauditingwithfailsafelogicand responsiveactionsincaseofanyidentifiedrisk. 2.Drosera:TheSecurityAutomationLayer ThenameDroseracomesfromageneraofcarnivorousplants.Theteamlikedtheidea thatalittleliquiditycouldbeusedtohelpprotocolscatchbugs.Itmadeusthinkabout howprotocolscanbesymbioticandhowquicklycatchingabugshouldbeincentivized. MostpeoplearefamiliarwiththetoothedsnaptrapsoftheVenusFlytrap,whichledusto thename“Traps”forournewsecurityprimitive. DroseraaimstoleveragethedecentralizednatureofEthereumconsensustocreateabase layerforsecurity.ProtocolsdefineincidentresponselogicforOperatorstocarryout. Slashingandrewardmechanismsensurehonestyandaccountability.Thisapproachto securityexpandsmonitoringandbugbountyprogramstoadynamicmodel.Drosera maintainsanopenandefficientplatform,encouragingcollaborationandshared knowledgeamongtheparticipatingparties.Thiscouldresultintheevolutionofadvanced securitysolutionsandbestpractices,contributingtotheoverallenhancementand resilienceoftheEthereumecosystem. Figure1:DroseraValue&TrustModel. Operatorsreceiverewardsforperformingincidentdetectionandresponse. Trapsaresecurityinfrastructureassoliditycode. ProtocolscreateTrapsandprovideoperatorsrewardsforapplicationsecurity. 2.1Drosera’sRole&Responsibilities Droseraaimstorevolutionizeincidentresponsebyprovidingaframeworkthatenables decentralizedincidentresponsesystems.Itcreatesaplatformforprotocolsandthe communitytocollaborateonincidentdetectionandresponse.Drosera'scoreroleis facilitatingtrustbetweenparticipants,whileitsresponsibilitiescenteraroundfosteringa secure,collaborative,andrewardingenvironment.ThisempowersbothProtocolsand Operatorstocontributetoasaferdecentralizedecosystem. Figure2:ATrap 2.2CoreConcepts ●Traps:ATrapisasecurityinfrastructuresmartcontractthatdefinesinstructions forperformingincidentresponsewhenrunbytheDroseranetwork. ●Operators:OperatorsarenodesintheDroseranetworkthatoptintoTrapsto receiverewardsandsecuretheEVM. ●HydrationStreams:AHydrationStreamisastreamoftokenscreatedfora specificTrapthatdistributesrewardstooperatorsrunningtheTrap.Anyonecan makeahydrationstreamatanytime. ●BloomBoost:ETHdepositedonaTrapthatbooststhepriorityoftheemergency responsetransaction. Figure3:DroseraSecurityMarketplace 3.Protocols:CultivatingSecurity ProtocolsuseDroseraasasecuritymarketplace. TheProtocol’sresponsibilitiesinclude: 1.Creatinga“detectionandresponse”contract,otherwisetermedaTrap a.Trapcontractbytecodelivesoff-chainwhileotherconfigurationsforthe Trapliveon-chaininaTrapConfigcontract 2.AllowfortheTrapConfigcontracttotriggertheemergencyresponsemechanism. 3.FillinguptherewardpoolforoperatorsthatoptintotheTrap. a.RewardsarefacilitatedthroughHydrationStreams.Theseallowtoken rewardstobestreamedtooperatorsovertimeandwhenincidentresponse isperformed. 4.BoostingtheemergencyresponsetransactionspeedviaBloom-Boost 3.1TrapLogic Trapsaresmartcontractsthatcollectandanalyzestatedatatodecidewhetheranincident hasoccurred.IfaTrap’sshouldRespondfunctionreturnstrue,anincidenthasbeen detected.Asimplecheckmaycomparetwovariablesinasmartcontract’sstorageto ensuretheyarealwaysthesame.Amoreadvancedcheckmaycollectandanalyzedata frommultiplesmartcontracts.TheDroseraOperatorsrunthesechecksoff-chain,and consensusontheresultsforeachblockisreachedviaBLSsignatureaggregation.For example,supposethetraplogicistodeterminewhethertheweightedsumoftheelements ofvector x equalsthesumofthevectory'scomponents.Wecanrepresentthisfunctionas follows: Thisfunctionreturnstrueiftheweightedsumofallelementsinvector x equalsthesum ofallelementsinvector y andfalseotherwise.Theresultisincludedinthesigned messageandbroadcastedtootherOperators.EachOperator i hasaprivatekey x i anda correspondingpublickeyg xi ,wheregisageneratoroftheellipticcurvegroup. SignatureGeneration:EachOperator i signsamessage m usingtheirprivatekey x i .The signatureσ i iscomputedas(H(m)) xi ,whereH(m)isacryptographichashfunctionthat maps m toapointontheellipticcurve. SignatureAggregation:Anaggregatorcollectsallsignatures σ i andaggregatesthemto formtheaggregatesignaturesigma. SignatureVerification:Toverifytheaggregatesignature σ ,checkifthefollowing equationholds: where e isabilinearpairingfunction. 3.2IncidentResponseMechanisms WhenOperatorsdetectthatanincidenthasoccurred,Drosera'sincidentresponse mechanismisexecutedimmediatelyupona⅔majorityconsensusandemergency transactioninclusion.Eachoperatorhastheopportunitytosubmittheclaimsignedbythe network.Thefirstincidentresponsetransactionincludedinablockwillexecutethe Trapsresponsefunction,andtheoperatorthatsubmittedthetransactionwillgetabonus rewardfortheincidentresponse.ThisiswhereDrosera'srapidreactioncapabilitiesplaya criticalroleinreducingtheimpactofanypotentialcompromise. 4.Operators:GuardingTheGreenhouse OperatorsserveasprotocolsentinelsbyoptingintoTrapsthatfittheirriskprofile. Carryingoutreal-timeincidentresponsetasksinvolvesrunningoff-chainlogicand vigilantlyexaminingtheEVMovertime.Operatorsperformconsensuswithother operatorsthroughpeer-to-peernetworkcommunication. TheOperator’sresponsibilitiesinclude: 1.OptingintooneormoreTraps. 2.Itrunsanoff-chainshadowforkoftheEVMthatexecutestheTrapcontract’s bytecode. 3.Aggregateclaimsof“shouldRespond”fromthenetworkofoperatorstocollect⅔ oftheOperator’ssignatures. 4.Broadcastclaimsof“shouldRespond”. 5.ItexecutestheincidentresponsemechanismwhenashouldRespond=true. Byoptingintoatrap,theoperatorcommitstoadditionalslashingconditions.Slashing holdsOperatorsaccountableforbadbehavior,whilerewardsincentivizeOperatorsto performtheirtasks. 4.1Attestationsofincidentresponse SimilartoEthereumconsensus,OperatorsaggregatedatathatotherOperatorsbroadcast. Operatorsusepeer-to-peercommunicationtoachievemajorityconsensusonthe protocol'sTrapcontractlogicresults.ThisallowsOperatorstodetectexactlywhenthe Trapanalysisidentifiesanincident,whichtriggersanincidentresponsemechanism. 4.1.1Claims A‘claim’isthedatabroadcastedfromanOperatortothenetworkofoperatorsvia peer-to-peercommunication.Claimsareasetofdatapackets,eachwithablock numberandtheTrapshouldRespondresult.Tobeconsideredvalid,theclaim mustbesignedbyatleast⅔ofthetotalOperators. 4.1.2Submissions Asubmissionisaclaimwith⅔ofallsignaturesandhasbeensubmittedtothe Ethereumnetwork.SubmissionsaresenttothemainDroseracontract,andthe incidentresponseisexecutedonthespecificTrap’sTrapConfigcontract.A submissionisonlyperformedwhenanincidentisdetected,andtheemergency responsemustbeexecuted. 4.2Rewards Droseracontainsmultiplerewardsystems.ThereareTrapRewardsforpassive/active participationintheTrapandStakingRewardsforusersthatstakeDrosera’snativetoken, DRO.Traprewardpercentagesareappliedtothehydra TrapRewards ○PassiveReward ■ 70%rewardspersecond. ■ Operatorsarepassivelygivenrewardsovertimebasedonthisreward percentage,thenumberofoperatorsoptedintothetrap,andactive hydrationstreams. ○ActiveReward ■ 20%rewardspersecond ■Abonusrewardpoolfillsupovertimebasedonthispercentage. ■ Anoperatorisgiven50%ofthebonusrewardforbeingthefirsttosubmit aclaimthatreaches2/3consensus.Whiletheother50%isdistributedto operatorsthatparticipatedinsigningtheclaimthatwassenton-chain. ○StakingReward ■10%rewardspersecond ■Drosera’sstakingpoolaccumulatesthispercentageofrewardsfromeach trap. Figure4:RewardFlow 4.2.1DROToken TheDROtokenisthenativetokenoftheDroseraprotocolandisusedforvarious functionswithintheecosystem.ItisanERC20-compatibletokenthatleverages theERC1363standardtocreateHydrationStreamsandTraps.Additionally,the DROtokenisusedforstakingandstakingrewardfacilitation. 4.2.2HydrationStreams TheHydrationStreamsystemallowsforthedistributionofrewardstoasetof operators.Therewardsaredistributedovertimeanddynamicallyallocatedbased onthenumberofoperatorswhohaveoptedintotheTrap.Additionally,the rewardsaredistributedtoabonusrewardpool(foremergencyresponse)andthe HarvesterPool(forstakingrewards). 4.2.3BonusRewards AbonusrewardpoolexistsforeachTrap,accumulatingapercentageoftokens fromhydrationstreamsovertime.Halfoftherewardamountisallocatedtoan operatorthatsubmitsanemergencyclaimthatreaches2/3consensus.Theother halfofthebonusrewardissplitbetweentheoperatorsthatparticipatedbysigning thesubmittedclaim.EachTraphasitsrewardcontractandbonusrewardpool. TheTrap'sassociatedrewardlogicfundsthepool. 4.2.4Staking StakingDROtokensintotheHarvesterallowsuserstoearnrewardsfromthe HarvesterPool.Therewardsaredistributedbasedonaweighteddistributionof theDROstakedandthedurationofthestake.Allhydrationstreamsdonatea percentageofrewardstotheHarvesterPool.ThisallowsuserstostaketheirDRO togenerateyieldtotheirprotocolsecuritybudget. 4.3Penalties&Slashing IftheclaimsfromasubmissionareprovenincorrectviaaSNARKproof,thenthesigners whoattestedtothesubmissionareslashed.Thisisacasewheremaliciousbehaviorcan beproven,andthepunishmentisdetrimentaltotheOperators.Slashingkicksthe operatorswhocolludedfromthenetworkandfreezesthemsotheycannotparticipatein Traps.Integratingwithrestakingplatformsinthefuturewillalsoallowforstakestobe slashed. 4.3.1Restaking TheDroserateamisprimarilyfocusedondevelopingDrosera’scorebusiness logicatthistime.RestakingintegrationisafeatureweplantobuildasDrosera matures.Leveragingre-stakingprotocolsforadditionalcrypto-economicsecurity allowsDroseratobolsteritssecurityposture,makingitavaluableadditionto Drosera’sfeatureset.Additionalresearchisbeingconductedtoidentifyhow restakingcanbeleveragedonEVML2s. 4.3.2MitigatingInactiveSigning TheDroserateamplanstodevelopamechanismthatdetectswhenanOperator hasnotsignedanyofthelastXsubmissionsandthenpenalizestheOperator. Monitoringpeer-to-peeractivityisasimplemeasuretodetectifanOperator atteststoblocksandcommunicateswithpeers. 4.3.3MitigatingCensorship TheDroserateamplanstodevelopamechanismtodetectrepeatedcensorshipby Operators.SupposeanOperatorhasrepeatedlynotincludedasignerintheirlast Xsubmissions.Inthatcase,theoperatorcanbepenalizedforcensorshipunless thesignerisidentifiedasnotactivelysigning. MitigatinginactivityandcensorshipisimportantforensuringahealthysetofOperators. Theteamplanstodeveloptheseslashingconditionsoncethecoreprotocolbusinesslogic hasmaturedandawideraudiencecanparticipate. 5.Drosera:UseCases TherehavebeenaplethoraofmajorhackssincethebeginningofDeFi.Common securityvulnerabilitiestendtobecaughtinthesmartcontractauditingphase,butmany hacksoccurbecauseofmisconfigurations,unforeseenscenarios,andundetecteddesign flaws.Criticalvulnerabilitiesarefounddailyinthetechindustry;asthesesystems becomemorecomplex,thereisahigherlikelihoodofhumanerror.Lookingbackat these,wecanidentifyhowDroseracouldbeusedinreal-worldscenarios.Thisshows howvaluableitisforaprotocoltohaveabuilt-indefensemechanism. 5.1AddressableMarket TheaddressablemarketforDroseraisexpansiveasthedecentralizedfinance(DeFi) ecosystemcontinuestogrowandevolve.DeFiprotocolsrecognizetheimportanceof securityandoftenimplementvarioussecuritymeasurestoprotecttheirusersandassets. Droserapresentsitselfasavaluablesolutiontothisgrowingmarketbyofferinga decentralizedsecuritybaselayer. Herearejustafewpre-existingprojectsthathavebuilt-indefensemechanisms: LendingandBorrowingDecentralizedExchangesDerivatives,Synthetics, andOptions MakerDAO Compound Aave Curve PancakeSwap Bancor KyberNetwork Synthetix DyDx Opium C.R.E.A.MFinance VenusProtocol 0x Balancer YieldFarm/AggregatorLiquidityManagementandStaking Yearn.Finance HarvestFinance RariCapital Alchemix IdleFinance BadgerDAO mStable Gnosis KeeperDAO AsDeFibecomesmorecomplexandadditionalprecautionsmustbetaken,protocolswill lookforwaystoprotecttheirapplicationsinadecentralizedcapacity. 5.2NomadHack TheNomadhackoriginatedwithatransactionat9:32pmUTC,whereanindividual successfullyextracted100WrappedBitcoin(WBTC)fromthebridge,valuedatroughly $2.3million.Followingthecommunity'sconcernsregardingapossiblebreach,the Nomadteamacknowledgedthesituationat11:35pmUTC,statingtheywereawareof theincidentandactivelyinvestigatingit.Theperpetratorsextractedtokensovera multi-blocktimeperiod,witheachwithdrawalamountingtoapproximately202,440 USDC.Thewithdrawaltransactionwasexecutedover200times.\[6\] Thishackisagoodexampleofamulti-blockcompromisewhereDroseracouldhelp mitigateongoingdamage.ImagineifDroseraoperatorsoptedintoaNomadTrapandran off-chaininfrastructuretodetectcompromisesbylookingatstatechangesintheEVM. TherearetwoscenarioswhereDroseracouldprovidetheprotocolandcommunitywith support: ExistingDefenseMechanism:IfNomadimplementedanemergencypausebuttonin theirsmartcontracts. ●Inthisscenario,theDroseraparticipantsdetectanincidentforNomad.Each operatorsignsanattestationthatacompromiseoccurred.Theincidentresponseis triggeredafterthedetectedcompromiseandcouldmitigatetheotherexploits. FireSignalMechanism:Nomadhasnoresponsemechanismimplementedintheirsmart contractstostopormitigatecompromises. ●Inthisscenario,theDroseraoperatorsdetectanincidentstateforNomad.Each participantsignsanattestationthatacompromiseoccurred,andtheincident responseistriggered.Duetothelackofadefensemechanismfortheprotocol, thisresponseactioncanonlyflagthestatechange,actingasafiresignalthatthe protocoliscompromised.Thiscanbeapublicwarningthatotherprotocols,users, andorganizationscanimmediatelybeawareoftheissue.Withnoresponse mechanismsavailable,theprotocolcannotdefenditself.However,theprotocol couldbeusedtoperformwhitehattransactions.DuringtheNomadHack, MoonbeamNetworkexerciseditswaytoprotectitselfandentered“maintenance mode.” 5.3WormholeHack Wormholeservedasadecentralizedtokenbridge,enablingthetransferof cryptocurrenciesacrossmultipleblockchainnetworks.Thebridgefellvictimtoasecurity exploit,leadingtothetheftof120,000WrappedEther(wETH)tokens,equivalentto $321million.TheattackerexploitedthesystembymintingwETHonSolanaand exchanging93,750wETHfor$254millioninETHontheEthereumnetwork.In response,theWormholeteamannounceda$10-millionbugbountytorecoverthestolen funds.\[7\] Thishackisagoodexampleofaprotocolusingadefensemechanism.Theprotocol hopesthebugbountywillincentivizethehackertoreturnthefunds.Unfortunately,hope isnotaneffectivestrategyfordamagemitigation.Droserawouldenableadefense mechanismwherethebugbountyfundscouldbeusedtopayparticipantsfortheir services.ImagineifDroseraoperatorsoptedintoaWormholeTraprunoff-chain infrastructuretodetectcompromises.ThesamescenariosapplyintheNomadhackcase providedabove.Thisallowstheoperatorstotakeemergencyactionwhentheyhaveall cometoconsensus. 6.AWorldWithDrosera 6.1DroseraEnablesNewApplications Drosera'sapproachtosecurityenablesthedevelopmentofnewapplicationswithbuilt-in defensemechanismstoprotectagainstrisks.Droseraallowsdeveloperstoexplorenovel usecasesandbuildcutting-edgedecentralizedapplications,knowingthattheirprojects willbeprotectedbyrobustsecurityinfrastructure.Droserareinforcestheexisting infrastructure,ensuringdecentralizedapplicationsandprotocolscanconfidentlyoperate. 6.2DroseraExpandsResponseMechanisms WithDrosera,theEthereumecosystembenefitsfromadiversearrayofresponse mechanismsthatgobeyondcurrentsecuritymeasures.Drosera'sapproachenablesthe rapiddetectionofcompromises,ensuringswiftandeffectiveresponsestosecuritythreats ultimatelymitigatingpotentialdamage.Drosera'sapproachtoincidentresponse encouragesacollaborativeenvironmentwheredevelopersandsecurityresearcherswork togethertoimprovetheoverallsecurityoftheecosystem. 6.3FlexibleMarketplaceforCustomizedResponses Drosera'sdesignenhancessecurityandoffersaversatilemarketplaceforprotocols seekingcustomizedresponsesbasedonspecificconditions.Forinstance,protocolscan triggeractionslikeswappingtokensinatreasuryifastablecoinde-pegs,bridgingtokens afteracertainblocknumber,orupdatingavault'sstrategyonceenoughstakersattest. Thisflexibilityallowsprotocolstoadaptandrespondeffectivelytovariousscenarios, fosteringamoreresilientandefficientdecentralizedecosystem. 6.4HiddenSecurityIntents Keepinganintenthiddenisanimportantfactorinadversarialsecurity.Knowingwhich conditionstriggeraprotocol'semergencysystemsislikegivinganadversarythe blueprintofamaze.Theywillknowwhichpathsleadtotrapsanddeadendsandwhich leverstopull.Essentially,hidingintentsallowsfornewapplicationsthatrequirethe “why”anactionisperformedtobeobscured/hidden. 6.5UsingBlockBuildingforRapidandBundledExecution AnalyzingDroserafromablock-buildingperspectiverevealsintriguingpossibilitiesfor leveragingBlockbuilderstosupportthenetwork'semergencyactions.Byincentivizing incidentresponse,Droseracanpromotefasterandbundledresponseexecution,enhancing thesystem'sefficiencyandabilitytoreacttopotentialcompromises.Thisinnovative approachtosecurityfurtherstrengthenstheEthereumecosystemanditsattractivenessto decentralizedapplicationsandprotocols. Figure5:BloomBoostDiagram 7.Summary:RootsToLeaves Droseraisarevolutionarysecuritymarketplacethatallowsprotocolstocreateanoasiswithin Ethereum'sdarkforest.ItenhancesthesecurityandresilienceoftheEthereumecosystem,driven bythecommunity,forthecommunity-allwhilesupportingbothnewandexistingapplications tothriveamidsttheever-changinglandscape.Byfosteringdecentralizedresponsestosecurity incidents,Droseraprovidesaframeworkforfightingbackagainstloomingthreats. References \[1\]Compromises2022: https://www.reuters.com/technology/crypto-hacks-stole-record-38-billion-2022-led-by-north-kor ea-groups-report-2023-02-01/ \[2\]FormalVerification: https://ethereum.org/en/developers/docs/smart-contracts/formal-verification/ \[3\]TrailofBitsFindings https://blog.trailofbits.com/2019/08/08/246-findings-from-our-smart-contract-audits-an-executiv e-summary/ \[4\]BeaconNodeEventStream: https://ethereum.github.io/beacon-APIs/#/Events/eventstream \[5\]EthereumRPCAPI: https://ethereum.org/en/developers/docs/apis/json-rpc/#json-rpc-methods \[6\]NomadHack: https://cointelegraph.com/news/nomad-token-bridge-drained-of-190m-in-funds-in-security-explo it \[7\]WormholeHack: https://cointelegraph.com/news/wormhole-token-bridge-loses-321m-in-largest-hack-so-far-in-20 22 --- # Drosera · Ethereum Evolved – Docs [Skip to content](https://dev.drosera.io/#vocs-content) Search... Menu Drosera · Ethereum Evolved ![Logo](https://dev.drosera.io/img/drosera-symbol.png) Drosera ![Logo](https://dev.drosera.io/img/drosera-symbol.png) Infinite bandwidth for smart contracts using decentralized, verifiable, and composable infrastructure [Introduction](https://dev.drosera.io/introduction) [GitHub](https://github.com/drosera-network) Terminal bash Copy `curl -L https://app.drosera.io/install | bash` [Start Trapping\ \ Creating traps with the `Drosera CLI`](https://dev.drosera.io/trappers/getting-started) [Running A Node\ \ Spinning up a Drosera operator](https://dev.drosera.io/operators/installation) [Litepaper\ \ High level drosera protocol and architecture](https://dev.drosera.io/litepaper) [Use Cases\ \ Novel ideas enabled by Traps and the drosera protocol](https://dev.drosera.io/use-cases) 🔍 ### Trap Explorer Explore and monitor all active traps in the Drosera network [Launch Trap Explorer](https://app.drosera.io/) 💧 ### Testnet Faucet Get test tokens to interact with the Drosera testnet [Get Tokens](https://faucet.drosera.io/) ♟️ ### Testnet Chess Play chess on-chain powered by a Drosera Trap [Play Chess](https://chess.drosera.io/) BlockNumberTrap.solTrapperCommands.shOperatorCommands.sh File BlockNumberTrap.sol Copy `// SPDX-License-Identifier: UNLICENSED pragma solidity ^0.8.12; import {Trap} from "drosera-contracts/Trap.sol"; contract BlockNumberTrap is Trap { // Define data collection points struct CollectOutput { uint256 blockNumber; } // Collect data every block function collect() external view returns (bytes memory) { return abi.encode( CollectOutput({blockNumber: block.number}) ); } // Time-series analysis on collected data over block-sample-size function shouldRespond( bytes[] calldata data ) external pure returns (bool, bytes memory) { CollectOutput memory collectOutput = abi.decode( data[0], // The most recent collected data point (i.e. most recent block) (CollectOutput) ); if (collectOutput.blockNumber == 845699) { // True: Perform response-function defined in drosera.toml return (true, abi.encode(collectOutput.blockNumber)); } // False: Do not perform response-function return (false, abi.encode(collectOutput.blockNumber)); } }` [![RiscZero](https://dev.drosera.io/risczero.png)](https://github.com/risc0) [![Foundry](https://dev.drosera.io/foundry.png)](https://github.com/foundry-rs/foundry) [![Revm](https://dev.drosera.io/revm.png)](https://github.com/bluealloy/revm) [![LibP2P](https://dev.drosera.io/libp2p.png)](https://github.com/libp2p) Drosera supports the following out of the box for a best-in-class developer experience: * Infinite bandwidth for smart contracts using [Drosera Traps](https://x.com/DroseraNetwork/status/1796210361940504956) * Verifiable infrastructure using [RiscZero](https://risczero.com/) zk proofs * Asynchronous composability between off-chain compute and on-chain state using just [Solidity](https://soliditylang.org/) * Fully testable infrastructure with existing Ethereum tooling such as [Foundry](https://getfoundry.sh/) * Tooling inspired by [Terraform](https://www.terraform.io/) * Decentralized and permissionless nodes powered by [LibP2P](https://libp2p.io/) for peer-to-peer networking Join the Community * Ask for support in the [Discord](https://discord.gg/drosera) or create a [request for Trap on Github](https://github.com/drosera-network/examples/issues) credit to alloy for providing vocs styles 🦾 --- # Getting Started – Docs [Skip to content](https://dev.drosera.io/trappers/getting-started#vocs-content) Search... [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) Menu Chevron Down Menu Getting Started On this page Chevron Right Installing Droseraup[](https://dev.drosera.io/trappers/getting-started#installing-droseraup) ----------------------------------------------------------------------------------------------- Droseraup is the Drosera CLI installer. It is a simple command line tool that allows you to install the Drosera CLI globally on your machine. Open your terminal and run the following command: Copy `curl -L https://app.drosera.io/install | bash` This will install Droseraup, then follow the instructions on-screen, which will make the `droseraup` command available in your CLI. Running `droseraup` by itself will install the latest precompiled `drosera` binary. See `droseraup --h` for more options, like installing from a specific version. ### Prerequisites[](https://dev.drosera.io/trappers/getting-started#prerequisites) * [Foundry](https://book.getfoundry.sh/getting-started/installation) Install Foundry Copy `curl -L https://foundry.paradigm.xyz | bash foundryup` ### Initialize Drosera project[](https://dev.drosera.io/trappers/getting-started#initialize-drosera-project) Use the Drosera Trap Foundry Template repo to easily create a new Drosera project. Copy `mkdir my-drosera-trap cd my-drosera-trap forge init -t drosera-network/trap-foundry-template` ### Quick Start[](https://dev.drosera.io/trappers/getting-started#quick-start) [Drosera Trap Foundry Template Repo](https://github.com/drosera-network/trap-foundry-template) --- # Introduction – Docs [Skip to content](https://dev.drosera.io/introduction#vocs-content) Search... [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) Docs Chevron Down Menu Introduction On this page Chevron Right [Drosera Trap Explorer](https://app.drosera.io/) Welcome to the **Drosera** developer documentation! This site contains documentation for: * [Litepaper](https://dev.drosera.io/litepaper) - A high-level overview of Drosera and its core components. * [Trappers](https://dev.drosera.io/trappers/getting-started) - Developers that create Traps. Traps are smart contracts responsible for gathering on-chain data and performing analysis over the collected data. Protocols can use Traps to monitor their on-chain state and signal the execution of an on-chain response function. * [Operators](https://dev.drosera.io/operators/installation) - Decentralized nodes that are responsible for executing Traps and performing on-chain response actions. Operators can opt into a Trap to gain permission to execute it and earn rewards. * [Seed Nodes](https://dev.drosera.io/introduction#seed-nodes) - Nodes that are responsible for hosting Traps and bootstrapping Operators into a decentralized network. What is Drosera?[](https://dev.drosera.io/introduction#what-is-drosera) -------------------------------------------------------------------------- Drosera is a passionate team of developers and researchers who are dedicated to building trustless and decentralized infrastructure for detecting exploits and mitigating financial loss. Drosera is an automation protocol that simplifies the process of creating monitoring systems for decentralized applications. It provides a framework for creating and executing automated responses to events on the Ethereum network, enabling developers to create more robust and secure applications. Born out of the need for a more robust security systems for DeFi protocols, Drosera is designed to be native to the Ethereum ecosystem with a strong foundation that can be built upon. Simplicity and developer friendliness were paramount in the design of Drosera, ensuring that its straightforward approach will allow for a wide range of use cases for off-chain monitoring and on-chain responses. As Drosera continues to evolve, we remain committed to providing a secure and user-friendly solution to the DeFi community. Our goal is to empower developers and users alike, fostering a more secure and robust DeFi ecosystem. How Does Drosera Work?[](https://dev.drosera.io/introduction#how-does-drosera-work) -------------------------------------------------------------------------------------- ![DroseraTrap](https://dev.drosera.io/img/drosera-trap.png) ### Traps[](https://dev.drosera.io/introduction#traps) Traps are a set of smart contracts that define the conditions for detecting invariants and performing on-chain responses. Traps have an on-chain and off-chain component that are described below: * **Trap** - An off-chain smart contract that performs data collection and analysis to signal the execution of an on-chain response function. * **Trap Config** - An on-chain smart contract that configures the trap and defines the on-chain response callback function. Example: "pause(uint256)" , "react(address)", etc. The Trap Config holds a hash of the Trap contract and the address of the on-chain response function. It is used to help coordinate the execution of the Trap and the on-chain response function with Operators as well as holding them accountable for doing so. ### Operators[](https://dev.drosera.io/introduction#operators) Operators are crucial players in Drosera, consisting of organizations and solo stakers who run the Drosera Operator Client software to help maintain and protect the DeFi ecosystem. These dedicated individuals are responsible for executing Traps and performing on-chain response actions, ensuring the security and stability of the network. To execute a Trap, an Operator must first gain permission by opting into the specific Trap. Once opted in, the Operator gains access to the off-chain Trap and the current peers in the network. This allows them to actively participate in monitoring and evaluating every new block based on the conditions set by the Trap. In the event that the conditions of a Trap are met, the Operator will promptly execute the on-chain response function. This swift action helps to mitigate potential threats and exploits. ### Seed Nodes[](https://dev.drosera.io/introduction#seed-nodes) Seed Nodes are at the core of the Drosera network, providing the infrastructure needed to host Traps and bootstrap Operators into a decentralized network. These nodes are responsible for hosting the Trap bytecode and providing it to Operators when they opt into a Trap. Only trusted Seed Nodes should be used to ensure the integrity of the Trap bytecode. Trusted Seed Nodes are listed in the [deployments](https://dev.drosera.io/deployments) section of the Drosera documentation. ### High Level Architecture[](https://dev.drosera.io/introduction#high-level-architecture) ![DroseraHighLevelArchitecture](https://dev.drosera.io/img/DroseraHighLevelArchitecture.png) Learn More[](https://dev.drosera.io/introduction#learn-more) --------------------------------------------------------------- The Drosera team publishes articles on X. You can find them [here](https://x.com/DroseraNetwork/articles) . Follow the Drosera team on X for the latest updates and announcements. --- # Installation – Docs [Skip to content](https://dev.drosera.io/operators/installation#vocs-content) Search... [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) Menu Chevron Down Menu Installation On this page Chevron Right The Drosera Operator runs on Linux. There are two core methods to obtain the Drosera Operator application: * Pre-built binaries * Docker Images Pre-built Binaries[](https://dev.drosera.io/operators/installation#pre-built-binaries) ----------------------------------------------------------------------------------------- Each Drosera Operator release includes pre-built binaries. You can download the latest release from the [Drosera Operator GitHub Releases page](https://github.com/drosera-network/releases/releases) . ### Platforms[](https://dev.drosera.io/operators/installation#platforms) Binaries are supported on the following platforms: * x86\_64-unknown-linux-gnu: AMD/Intel 64-bit processors (most desktops, laptops, servers) ### Usage[](https://dev.drosera.io/operators/installation#usage) Each binary is contained in a .tar.gz archive. To use the Drosera Operator binary, follow the following steps: #### Steps[](https://dev.drosera.io/operators/installation#steps) 1. Go to the [Releases](https://github.com/drosera-network/releases/releases) page and select the latest release. 2. Download the `drosera-operator-${VERSION}-x86_64-unknown-linux-gnu.tar.gz` binary. For example, to obtain the binary file for v1.0.0-main.1 (the latest version at the time of writing), a user can run the following commands in a linux terminal: Copy `cd ~ curl -LO https://github.com/drosera-network/releases/releases/download/v1.0.2/drosera-operator-v1.0.2-x86_64-unknown-linux-gnu.tar.gz tar -xvf drosera-operator-v1.0.2-x86_64-unknown-linux-gnu.tar.gz` > The "main.1" suffix indicates a pre-release. 3. Test the binary with `./drosera-operator --version` to verify the binary is working and the version matches the expected version. 4. (Optional) Move the drosera-operator binary to a location in your PATH, so the drosera-operator command can be called from anywhere. For example, to copy drosera-operator from the current directory to usr/bin, run `sudo cp drosera-operator /usr/bin`. Docker[](https://dev.drosera.io/operators/installation#docker) ----------------------------------------------------------------- We also provide Docker images for the Drosera Operator. The Docker image can be obtained by pulling from our public registry: Copy `docker pull ghcr.io/drosera-network/drosera-operator:latest` Test the Docker image by running the following command: Copy `docker run ghcr.io/drosera-network/drosera-operator --help` Recommended System Requirements[](https://dev.drosera.io/operators/installation#recommended-system-requirements) ------------------------------------------------------------------------------------------------------------------- The Drosera Operator is a lightweight application that can run on most modern systems. However, we recommend the following system requirements for optimal performance: * 2 CPU Cores * 4 GB RAM * 20 GB Disk Space The more traps you are opted into, the more resources the Drosera Operator will consume. We recommend starting with the above requirements and scaling up as needed. --- # Litepaper – Docs [Skip to content](https://dev.drosera.io/litepaper#vocs-content) Search... [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) Menu Chevron Down Menu Litepaper On this page Chevron Right The Drosera Litepaper provides a high-level overview of Drosera and its core components. It is intended to give readers a basic understanding of the Drosera protocol and its use cases. The Litepaper is a living document and will be updated as the Drosera protocol evolves. [Drosera Litepaper](https://dev.drosera.io/pdfs/DroseraLitepaper.pdf) --- # Use Cases – Docs [Skip to content](https://dev.drosera.io/use-cases#vocs-content) Search... [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) Menu Chevron Down Menu Use Cases On this page Chevron Right There are infinite possibilities! * **Infrastructure as Code**: Define your incident response infrastructure as solidity code and deploy it with `drosera apply`. * **Time-series analysis**: Drosera Traps can access historical state data within solidity code just by querying an array `data[block_3,block_2,block_1]`. * **Automated Response**: Drosera Traps can be configured to execute any smart contract function within the EVM and specify inputs `performAction() or performAction(anyData)`. Below are some examples of how Drosera can be used for various DeFi use cases. Lending[](https://dev.drosera.io/use-cases#lending) ------------------------------------------------------ **Automated Liquidation Responses:** Detect if a user’s collateralization ratio drops below a critical level and initiate an automated response to either notify the user or trigger partial liquidation to avoid full liquidation. Monitor getInterestRate, getUtilization, and collateralBalanceOf over time to foresee potential mass liquidations. **Liquidation and Collateralization Safety Nets:** Ensure that collateralization ratios and liquidation patterns are stable and fair, protecting against erroneous liquidations or malicious actors trying to exploit the liquidation system. Decentralized Exchanges[](https://dev.drosera.io/use-cases#decentralized-exchanges) -------------------------------------------------------------------------------------- **Analyzing volume, liquidity, pricing, pool info:** Perform any action in response to detecting volumes, liquidity, and pricing changes. L2/Rollups[](https://dev.drosera.io/use-cases#l2rollups) ----------------------------------------------------------- **Monitoring state transitions, fraud proofs, and dispute resolution:** Monitor `pause` statuses to automatically notify users or halt interactions in the case where an L2 bridge is paused. Track the frequency of failedMessages and activate alerts or even halt certain operations if a threshold of failed cross-domain messages is reached. Yield Farms and Staking[](https://dev.drosera.io/use-cases#yield-farms-and-staking) -------------------------------------------------------------------------------------- **Reward Draining Mitigation:** Watch the rewardRate and total rewards over time to detect abnormal drains and potentially halt reward distributions or inform governance. Monitor deposit, escrow, and lockIncentive data to avoid smart contract bugs or exploits related to staking and unstaking mechanisms. **Stake and Yield Retrieval Stability:** Watch the balance and approval functions, especially regarding high-stake accounts, ensuring that stakers can retrieve their yields and principal smoothly, with no smart contract hitches. Oracles[](https://dev.drosera.io/use-cases#oracles) ------------------------------------------------------ **Data Integrity Checks:** Perform time series analysis on oracle data to ascertain data consistency and trigger alarms in cases of unusual data fluctuations which might indicate oracle manipulation or errors. **Guard Against Price Manipulation:** Monitor historical price feeds for sudden drastic changes, which may imply some risk, and enact protective measures. Privacy Solutions[](https://dev.drosera.io/use-cases#privacy-solutions) -------------------------------------------------------------------------- **Analysis on mixers:** Monitor the mixer’s state and user activity to detect potential malicious activities. Insurance Protocols[](https://dev.drosera.io/use-cases#insurance-protocols) ------------------------------------------------------------------------------ **Claim Anomaly Detection:** Continuously analyze claim data to identify patterns of fraudulent claims or unexpected spikes in claim requests. **Assessment and Voting Anomalies:** Analyze patterns in votes and rewards to identify malicious actors or manipulation in assessment voting. Collateralized Debt Positions[](https://dev.drosera.io/use-cases#collateralized-debt-positions) -------------------------------------------------------------------------------------------------- **Collateral Crisis Prevention:** Monitor totalDebt and positionCollateral to predict and prevent potential collateral crises and safeguard against deleveraging spirals. Cross-Chain Bridges[](https://dev.drosera.io/use-cases#cross-chain-bridges) ------------------------------------------------------------------------------ **Finality and Transfer Anomalies:** Continuously verify getFinality and isTransferCompleted to ensure asset security and bridge functionality, activating alerts, or partial functionality suspensions on anomalies. **Staked Assets:** Monitor staked assets and collateralization ratios to mitigate bridge failures or asset losses. Bug Bounty Platforms[](https://dev.drosera.io/use-cases#bug-bounty-platforms) -------------------------------------------------------------------------------- **Bounty Drain Protection:** Monitor `bountyAmount` and the status of bounties to detect unexpected drains or exploit attempts. Supervise `approvedSubmissions` and `rejectedSubmissions` for unusual activities, which might indicate collusion or fraudulent behaviors. Algorithmic Stablecoins[](https://dev.drosera.io/use-cases#algorithmic-stablecoins) -------------------------------------------------------------------------------------- **Stability Mechanism Checks:** Continuously evaluate and analyze token minting, burning, and collateralization rates for any signs that might jeopardize the peg stability. Regulatory Compliance[](https://dev.drosera.io/use-cases#regulatory-compliance) ---------------------------------------------------------------------------------- **Compliance And Regulatory Adherence:** Ensure that minting and redemption of tokens follow regulatory and compliance standards by monitoring state and ensuring they adhere to predefined rules. Custom data regarding jurisdictional regulatory requirements (like KYC/AML) can be monitored. When deviations or potential violations are detected, Drosera could enact responses, like freezing functionality or alerting relevant parties, to ensure protocols stay compliant. Pausable Functionality[](https://dev.drosera.io/use-cases#pausable-functionality) ------------------------------------------------------------------------------------ **Auto-Halt in Case of Unusual Activity:** Drosera detects abnormal behavior like rapid treasury drains, excessive minting of tokens, or sudden spikes in governance proposals and automatically triggers the isPaused function to halt activity, protecting users and assets. Protocol Configs[](https://dev.drosera.io/use-cases#protocol-configs) ------------------------------------------------------------------------ **Config Change Alerts:** Analyze and alert governance or users when vital config variables and constants change unexpectedly, which might impact tokenomics, protocol security, or user experience. Governance Mechanisms[](https://dev.drosera.io/use-cases#governance-mechanisms) ---------------------------------------------------------------------------------- **Mitigating Governance Attacks:** Analyze proposalInfo and voting patterns to safeguard against malicious governance attacks or unintended voting manipulations. Analyze token movement, approvals, and voting patterns (votes and proposalInfo) to guard against malicious governance takeovers or Sybil attacks. **Ensuring Healthy Governance:** Analyze participation and proposal outcomes, ensuring they align with a healthy, decentralized governance model and alert in case of centralized voting power emergence. Multisigs[](https://dev.drosera.io/use-cases#multisigs) ---------------------------------------------------------- **Multisig Operation Alerts:** Trigger alerts or potential pauses if there’s a mismatch between votes and threshold for multi-signature activities, ensuring all operations adhere to organizational and security protocols. **Unauthorized Activity Monitoring:** Observe activity to catch and react to unauthorized or unusual transactions that could indicate a compromise. Treasury Management[](https://dev.drosera.io/use-cases#treasury-management) ------------------------------------------------------------------------------ **Automated Treasury Health Checks:** Continuously check the balance and expenditures from the protocol's treasury, ensuring financial stability and alerting if unusual or unauthorized transactions occur. Token Management[](https://dev.drosera.io/use-cases#token-management) ------------------------------------------------------------------------ **Detect and Mitigate Token Minting Abuses:** Observe totalSupply, getBalance, and owners data to prevent unauthorized token minting or transfer events, ensuring tokenomics remain unharmed. **Approval and Token Spending Anomalies:** Check approval functions and movement of tokens to ensure no unexpected, unauthorized, or fraudulent activities are occurring related to token spending. Adaptive Fee Mechanism for Scalability and Affordability[](https://dev.drosera.io/use-cases#adaptive-fee-mechanism-for-scalability-and-affordability) -------------------------------------------------------------------------------------------------------------------------------------------------------- **Dynamic Fee Adjustments:** Using Drosera to monitor network congestion, gas prices, and protocol usage to dynamically adjust fees or yield returns to maintain a balance between protocol profitability and user incentivization during different network conditions. Automated Hedge Strategies[](https://dev.drosera.io/use-cases#automated-hedge-strategies) -------------------------------------------------------------------------------------------- **Market Impact Shields:** For yield protocols or DAO treasuries, employ Drosera to watch market conditions and automatically execute hedge strategies (like moving to stable assets) during negative market shocks, preserving value while maintaining decentralized governance. Smart Contract Upgradability and Migration Helper[](https://dev.drosera.io/use-cases#smart-contract-upgradability-and-migration-helper) ------------------------------------------------------------------------------------------------------------------------------------------ **Contract Evolution Monitoring:** Observing and assisting in smart contract upgrades or migrations. If data from a new contract version does not align with expected states (perhaps due to a bug or misconfiguration), Drosera can halt processes and alert developers before wider impact occurs. Inter-Protocol Synergy Checker[](https://dev.drosera.io/use-cases#inter-protocol-synergy-checker) ---------------------------------------------------------------------------------------------------- **Protocol Interaction Observing:** Observe interactions between different protocols to detect early signs of potential issues in composability or unexpected behavior due to updates/changes in one of the interconnected protocols, securing the broader defi ecosystem. Defi Product Insurance Parametric Triggers[](https://dev.drosera.io/use-cases#defi-product-insurance-parametric-triggers) ---------------------------------------------------------------------------------------------------------------------------- **Parametric Insurance Activator:** Drosera could execute automatic claim processing or payout triggers in decentralized insurance protocols by verifying on-chain data points that indicate a claim condition (such as smart contract failure or DEX price impact) has been met. Liquid Restaking[](https://dev.drosera.io/use-cases#liquid-restaking) ------------------------------------------------------------------------ **Mitigating Depegs:** Analyze the state of liquid restaking mechanisms to prevent depegs or sudden price fluctuations due to ecosystem events. **Handling Restaking Failures:** Observe restaking mechanisms to ensure that restaking failures are detected and resolved quickly, preventing loss of rewards or staking assets. Integrating with other protocols[](https://dev.drosera.io/use-cases#integrating-with-other-protocols) -------------------------------------------------------------------------------------------------------- **Anyone can use Drosera:** Other protocols and projects can enhance their product with one or many Drosera Traps. Next Block Response[](https://dev.drosera.io/use-cases#next-block-response) ------------------------------------------------------------------------------ **Priority Transactions:** Drosera can boost response transaction priority in order to ensure that critical actions are executed in the next block. On-the-fly Infrastructure Updates[](https://dev.drosera.io/use-cases#on-the-fly-infrastructure-updates) ---------------------------------------------------------------------------------------------------------- **Automated Infrastructure Updates:** Drosera can be used to automatically update infrastructure configurations based on on-chain data, ensuring that the infrastructure is always up-to-date and optimized. Drosera Traps themselves can also be updated on-the-fly. Pushing Off-chain Data to On-chain[](https://dev.drosera.io/use-cases#pushing-off-chain-data-to-on-chain) ------------------------------------------------------------------------------------------------------------ **Protocol Data Push:** Protocols can push data on-chain by simple creating contracts that take data from an admin or multisig. A Trap can be built to analyze the data from the contract and take action depending on its implementation. Protocol Dependency Risk Analysis[](https://dev.drosera.io/use-cases#protocol-dependency-risk-analysis) ---------------------------------------------------------------------------------------------------------- **Dependency Risk Mitigation:** Drosera can be used to analyze dependencies and alert/respond when a dependency is at risk of failure or has failed. And many more! Do you have a use case in mind? [Let us know](https://x.com/DroseraNetwork) ! --- # Updating a Trap – Docs [Skip to content](https://dev.drosera.io/trappers/updating-a-trap#vocs-content) Search... [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) Menu Chevron Down Menu Updating a Trap On this page Chevron Right After a Trap has been deployed to the Drosera Network, it is possible to update the Trap's bytecode and other configuration values such as the response contract and function. This is useful when a Trap needs to be updated with new logic or bug fixes. To apply the new changes after updating a Trap, simply run: Copy `drosera apply` If the Trap's bytecode, Seed Node DNR, or block sample size has changed, the Operators will need to restart the execution of the trap. This is an automatic process that will occur once the Trap update event has been detected by the Operators. The Seed Node DNR contains connection information of the Seed Node that the Operators use to retrieve the Trap bytecode and bootstrap into a decentralized network of other Operators. This is determined automatically when creating or updating the Trap. This values changes when the `drosera-rpc` argument is changed to a different Seed Node. --- # Boosting a Trap – Docs [Skip to content](https://dev.drosera.io/trappers/boosting-a-trap#vocs-content) Search... [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) Menu Chevron Down Menu Boosting a Trap On this page Chevron Right Drosera allows anyone to increase the priority of a Trap's response action by leveraging the Bloom Boost mechanism. By depositing ETH, a Trap's response action will have boosted priority to be included on-chain as soon as possible. This allows for lightning-fast incident response times to be achieved. To boost a trap, simply run: Copy `drosera bloomboost --trap-address
--eth-amount ` --- # Hydrating a Trap – Docs [Skip to content](https://dev.drosera.io/trappers/hydrating-a-trap#vocs-content) Search... [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) Menu Chevron Down Menu Hydrating a Trap On this page Chevron Right Drosera acts as a marketplace between Trappers and Operators. Operators are looking for the most incentivized traps to run, while Trappers are looking for Operators to run their traps. Hydration Streams are the main reward mechanism in the Drosera protocol. When a User creates a hydration stream, they fund the trap with any amount of Drosera's native token, and then the hydration balance is streamed out from the trap over-time to operators that have opted-into the trap. ![Hydration Streams Design](https://dev.drosera.io/trappers/img/HydrationStreams.png) Passive Rewards[](https://dev.drosera.io/trappers/hydrating-a-trap#passive-rewards) -------------------------------------------------------------------------------------- A majority of the hydration stream is distributed to the Operators that have opted into the trap. The rewards are split evenly between Operators. Active Rewards[](https://dev.drosera.io/trappers/hydrating-a-trap#active-rewards) ------------------------------------------------------------------------------------ Every trap has a bonus reward pool that continuously accumulates rewards from hydration streams. This pool is used as an active reward for Operators that submitted a response on-chain first. Operators that signed the claim via peer-to-peer communication also receive a portion of the bonus reward for participation. Staking Rewards[](https://dev.drosera.io/trappers/hydrating-a-trap#staking-rewards) -------------------------------------------------------------------------------------- Lastly, a portion of the hydration stream is streamed to the Drosera staking rewards pool. This pool is used to reward users that stake Drosera's native token. Creating a Hydration Stream[](https://dev.drosera.io/trappers/hydrating-a-trap#creating-a-hydration-stream) -------------------------------------------------------------------------------------------------------------- Hydration Streams can be created at any time by multiple users. To create a hydration stream on a Trap, simply run: Copy `drosera hydrate --trap-address
--dro-amount ` --- # Creating a Trap – Docs [Skip to content](https://dev.drosera.io/trappers/creating-a-trap#vocs-content) Search... [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) Menu Chevron Down Menu Creating a Trap On this page Chevron Right The section below outlines the anatomy of a Trap and how to deploy a Trap to the Drosera Network. Trap Anatomy[](https://dev.drosera.io/trappers/creating-a-trap#trap-anatomy) ------------------------------------------------------------------------------- Copy `// SPDX-License-Identifier: MIT pragma solidity ^0.8.24; struct EventLog { // The topics of the log, including the signature, if any. bytes32[] topics; // The raw data of the log. bytes data; // The address of the log's emitter. address emitter; } struct EventFilter { // The address of the contract to filter logs from. address contractAddress; // The topics to filter logs by. string signature; } abstract contract Trap { EventLog[] private eventLogs; function collect() external view virtual returns (bytes memory); function shouldRespond( bytes[] calldata data ) external pure virtual returns (bool, bytes memory); function eventLogFilters() public view virtual returns (EventFilter[] memory) { EventFilter[] memory filters = new EventFilter[](0); return filters; } function version() public pure returns (string memory) { return "2.0"; } function setEventLogs(EventLog[] calldata logs) public { EventLog[] storage storageArray = eventLogs; // Set new logs for (uint256 i = 0; i < logs.length; i++) { storageArray.push(EventLog({ emitter: logs[i].emitter, topics: logs[i].topics, data: logs[i].data })); } } function getEventLogs() public view returns (EventLog[] memory) { EventLog[] storage storageArray = eventLogs; EventLog[] memory logs = new EventLog[](storageArray.length); for (uint256 i = 0; i < storageArray.length; i++) { logs[i] = EventLog({ emitter: storageArray[i].emitter, topics: storageArray[i].topics, data: storageArray[i].data }); } return logs; } }` Source code for the abstract Trap contract can be found [here](https://github.com/drosera-network/contracts/src/Trap.sol) . Templates for common monitoring behavior can be found [here](https://github.com/drosera-network/trap-templates) . Collect Function[](https://dev.drosera.io/trappers/creating-a-trap#collect-function) --------------------------------------------------------------------------------------- The `collect` function is responsible for gathering data from the blockchain and returning it in a standardized format. This function is called by Operators on every new block and the output is stored off-chain on the Operator node. Example: Copy `function collect() external view returns (bytes memory) { uint256 totalSupply = IERC20(0x1234).totalSupply(); return abi.encode(totalSupply); }` Should Respond Function[](https://dev.drosera.io/trappers/creating-a-trap#should-respond-function) ----------------------------------------------------------------------------------------------------- The `shouldRespond` function is responsible for validating the data returned by the `collect` function. This function is called by the Operator on every new block and is used to determine whether or not the Trap response should be executed on-chain. The `collect` function is called first followed by the `shouldRespond` function. The `shouldRespond` function takes an array of bytes as an argument. The Operator will call the `shouldRespond` function with the previous data returned by the `collect` function. The outputs are ordered from newest to oldest. The last element in the array is the oldest block of data returned by the `collect` function. The first element in the array is the most recent block of data returned by the `collect` function. The `shouldRespond` function must return a tuple `(bool, bytes memory)`. If the tuple contains `true` then the Trap response **will** be executed. If the tuple contains `false` then the Trap response **will not** be executed by the Operators. The second element of the tuple is passed as an argument to the defined response function. Example: Copy `function shouldRespond( bytes[] calldata data ) external override pure returns (bool, bytes memory) { // Grab the total supply from the first element in the array (newest block) uint256 totalSupply = abi.decode(data[0], (uint256)); if (totalSupply < 1000000) { return (true, abi.encode(totalSupply)); } return (false, abi.encode("")); }` Set Event Logs Function[](https://dev.drosera.io/trappers/creating-a-trap#set-event-logs-function) ----------------------------------------------------------------------------------------------------- The `setEventLogs` function is responsible for setting the event logs emitted in a block in the Trap. This function is called by the Operator on every new block and is used to store the event logs and be made available to the `collect` function. This function is designated to be used by the off-chain operator node and is not intended to be called by the Trap developer. Get Event Logs Function[](https://dev.drosera.io/trappers/creating-a-trap#get-event-logs-function) ----------------------------------------------------------------------------------------------------- The `getEventLogs` function is responsible for returning the event logs emitted in a block in the Trap. This function can be called in the `collect` function to retrieve the event logs stored in the Trap. Example: Copy `function collect() external view override returns (bytes memory) { EventLog[] memory logs = getEventLogs(); EventFilter[] memory filters = eventLogFilters(); uint256 totalTransferAmount = 0; for (uint256 i = 0; i < logs.length; i++) { EventLog memory log = logs[i]; // Check if the log matches the filter for Transfer events by contract address and signature if (filters[0].matches(log)) { (,, uint256 amount) = parseTransferEvent(log); totalTransferAmount += amount; } // Check if the log matches the filter for Transfer events by signature if (filters[0].matches_signature(log)) { (,, uint256 amount) = parseTransferEvent(log); totalTransferAmount += amount; } } CollectOutput memory output = CollectOutput({ totalTransferAmount: totalTransferAmount }); return abi.encode(output); }` Event Log Filters Function[](https://dev.drosera.io/trappers/creating-a-trap#event-log-filters-function) ----------------------------------------------------------------------------------------------------------- The `eventLogFilters` function is responsible for returning an array of event filters that the Trap wants to evaluate. The event filters are used to match against event logs emitted in a block. This is purely a convenience function for the Trap developer to define the event filters they want to evaluate. Full and partial event filter matching is supported. For example, if the Trap wants to match against all Transfer events, it can return the following: Example: Copy `function eventLogFilters() public pure returns (EventFilter[] memory) { EventFilter[] memory filters = new EventFilter[](1); filters[0] = EventFilter({ contractAddress: address(0x0), // "Transfer(address indexed from, address indexed to, uint256 value)" signature: "Transfer(address,address,uint256)" }); }` If the Trap wants to match against all Transfer events from the `0x1234` contract, it can return the following: Copy `function eventLogFilters() public pure returns (EventFilter[] memory) { EventFilter[] memory filters = new EventFilter[](1); filters[0] = EventFilter({ contractAddress: address(0x1234), // "Transfer(address indexed from, address indexed to, uint256 value)" signature: "Transfer(address,address,uint256)" }); }` Version Function[](https://dev.drosera.io/trappers/creating-a-trap#version-function) --------------------------------------------------------------------------------------- The `version` function is responsible for returning the version of the Trap. This function is used to identify the version of the Trap and is used by the Operator nodes to determine how to execute the Trap. Deploying a Trap[](https://dev.drosera.io/trappers/creating-a-trap#deploying-a-trap) --------------------------------------------------------------------------------------- Once you have created and tested your Trap, you can deploy it to the Drosera Network. Run the drosera apply command to deploy your Trap to the network. Copy `drosera apply` A successful Trap creation will output the following: Copy `1. Created Trap Config for basic_trap: (Gas Used: 1,678,320) - address: 0x7ab4C4804197531f7ed6A6bc0f0781f706ff7953 - block: 321` The address represents the address of the Trap Config contract on the blockchain. The address will be used to interact with the Trap Config contract in the future. The Trap Config is used to store the hash of the Trap bytecode and the configuration of the Trap. The Trap Config is used by the Operators to determine which Traps to opt into and execute. The hash of the Trap bytecode is used to verify the Trap bytecode has not been tampered with and to request it from the configured Drosera RPC node. The response contract address and function signature are also stored in the Trap Config. Once a Trap indicates a response should be triggered, the Operators will submit a claim on-chain which will subsequently trigger the response function. Once the Trap Config has been created, the Trap bytecode will be sent to the configured Drosera RPC node. The Drosera RPC node will store the Trap bytecode and provide it to Operators when they opt into the Trap. The hash of the Trap bytecode is verified against the hash stored in the Trap Config to ensure the bytecode has not been tampered with. --- # Drosera CLI – Docs [Skip to content](https://dev.drosera.io/trappers/drosera-cli#vocs-content) Search... [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) Menu Chevron Down Menu Drosera CLI On this page Chevron Right The Drosera CLI is a command line tool used to create, manage, and monitor Traps on the Drosera Network. It utilizes a configuration file to manage your Traps and their configurations. It can be installed by following the getting started guide [here](https://dev.drosera.io/trappers/getting-started#installing-droseraup) . Configuration[](https://dev.drosera.io/trappers/drosera-cli#configuration) ----------------------------------------------------------------------------- ### Drosera.toml[](https://dev.drosera.io/trappers/drosera-cli#droseratoml) The `drosera.toml` file is used to configure the Drosera CLI. The file is used to define Drosera and chain connection info as well as the traps that are being managed and the response contracts that are triggered when a trap is triggered. Copy `ethereum_rpc = "http://examplerpc.io" drosera_rpc = "https://relayer.testnet.drosera.io" [traps] [traps.hello_world] path = "out/HelloWorldTrap.sol/HelloWorldTrap.json" response_contract = "0xea08f7d533C2b9A62F40D5326214f39a8E3A32F8" response_function = "pause(uint256)" cooldown_period_blocks = 33 min_number_of_operators = 1 max_number_of_operators = 2 block_sample_size = 10 private_trap = false whitelist = []` #### Connection Info[](https://dev.drosera.io/trappers/drosera-cli#connection-info) * `ethereum_rpc`: The ethereum RPC URL to send transactions with and read chain state. URL must be prepended with "http://". _Pointing to an ethereum archive node may be necessary for using the `dryrun` command historically_. * `drosera_rpc`: The URL of the seed node you wish to use. You can find seed nodes hosted by the Drosera team [here](https://dev.drosera.io/deployments#seed-nodes) . URL must be prepended with "http://" * (Optional) `eth_chain_id`: The chain ID that corresponds to the `ethereum_rpc`. **If this field is not included, the chain ID will be determined for you**. * (Optional) `drosera_address`: The address of the core Drosera contract on-chain. **If this field is not included, the address will be determined for you**. #### Trap(s) Info[](https://dev.drosera.io/trappers/drosera-cli#traps-info) * `traps`: The section where all the traps are defined. * `traps.`: The name of the trap. * `path`: The path to the trap's JSON file that contains the ABI and bytecode. * `response_contract`: The address of the contract to call when a response is triggered. * `response_function`: The function signature to call on the response contract. * `cooldown_period_blocks`: The number of blocks to wait before triggering another response. * `min_number_of_operators`: The minimum number of operators to execute the trap and trigger a response. * `max_number_of_operators`: The maximum number of operators that can opt into the trap. * `block_sample_size`: The number of blocks required by the `shouldRespond` function to make a decision. * `private_trap`: A boolean value that determines if the trap is private or public. Private traps can only be opted-into by trap-whitelisted operators. Default is `false`. * `whitelist`: A list of operator addresses that are allowed to opt into the trap. \["0x..", "0x.."\]. ### Private Key[](https://dev.drosera.io/trappers/drosera-cli#private-key) Most CLI commands require a private key as they are executing transactions. Your private key can be set as either an environment variable or as a CLI argument in applicable commands. Setting as an environment variable is the easiest method. Example Copy `export DROSERA_PRIVATE_KEY=ac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80` ### CLI Arguments[](https://dev.drosera.io/trappers/drosera-cli#cli-arguments) | Argument | Default | Description | | --- | --- | --- | | `--config-path (-c)` | Looks in current and parent directories | The path to the drosera.toml file | | `--non-interactive (-n)` | False | Determines if a user prompt is required before creating or updating traps | ### Commands[](https://dev.drosera.io/trappers/drosera-cli#commands) The CLI command options can be configured using CLI arguments, the drosera.toml config file, or with environment variables. A combination of either can also be used. The order of precedence is as follows: * Command line arguments * TOML configuration file `./drosera.toml` * Environment variables / .env file NOTE: Make sure to run the CLI from the same directory as the `drosera.toml` file. The `DROSERA_PRIVATE_KEY` environment variable is required to deploy or update a trap. #### `config`[](https://dev.drosera.io/trappers/drosera-cli#config) Displays the current configuration file. #### `plan`[](https://dev.drosera.io/trappers/drosera-cli#plan) Displays the traps that will be created or updated based on the configuration file. ##### Args[](https://dev.drosera.io/trappers/drosera-cli#args) | Argument | Default | Description | | --- | --- | --- | | `--eth-rpc-url` | | The node used for querying and sending transactions | | `--drosera-rpc-url` | | The url of the seed node to send the trap bytecode to | | `--eth-chain-id` | derived from the ethereum rpc | The chain id | | `--private-key` | | The private key used to sign transactions | | `--drosera-address` | derived from chain id | The address of the main Drosera proxy contract to interact with | #### `dryrun`[](https://dev.drosera.io/trappers/drosera-cli#dryrun) Runs all traps in the `drosera.toml` file on a local ad-hoc operator, testing the `collect` and `shouldRespond` functions. This is also run for you automatically in the `apply` command. Additionally you can theory-craft by testing traps historically. ##### Args[](https://dev.drosera.io/trappers/drosera-cli#args-1) | Argument | Default | Description | | --- | --- | --- | | `--eth-rpc-url` | | The node used for querying and sending transactions | | `--eth-chain-id` | derived from the ethereum rpc | The chain id | | `--drosera-address` | derived from chain id | The address of the main Drosera proxy contract to interact with | | `--block-number` | current block number | The block number to perform the dryrun on. This allows historical testing of trap behavior | #### `apply`[](https://dev.drosera.io/trappers/drosera-cli#apply) Creates or updates traps based on the configuration file. If an address field is specified in the configuration file, the trap is updated. If the address field is not specified, the trap is created and the address of the deployed Trap Config address is set in the config file by the CLI. ##### Args[](https://dev.drosera.io/trappers/drosera-cli#args-2) | Argument | Default | Description | | --- | --- | --- | | `--eth-rpc-url` | | The node used for querying and sending transactions | | `--drosera-rpc-url` | | The url of the seed node to send the trap bytecode to | | `--eth-chain-id` | derived from the ethereum rpc | The chain id | | `--private-key` | | The private key used to sign transactions | | `--drosera-address` | derived from chain id | The address of the main Drosera proxy contract to interact with | | `--non-interactive` | false | Normally the command will prompt you for final approval before executing. This will bypass that check. | #### `hydrate`[](https://dev.drosera.io/trappers/drosera-cli#hydrate) Hydrate the specified trap. This is how you incentivize operators to monitor your trap. This sends DRO to the traps' `trap_rewards` contract. ##### Args[](https://dev.drosera.io/trappers/drosera-cli#args-3) | Argument | Default | Description | | --- | --- | --- | | `--eth-rpc-url` | | The node used for querying and sending transactions | | `--drosera-rpc-url` | | The url of the seed node to send the trap bytecode to | | `--eth-chain-id` | derived from the ethereum rpc | The chain id | | `--private-key` | | The private key used to sign transactions | | `--drosera-address` | derived from chain id | The address of the main Drosera proxy contract to interact with | | `--non-interactive` | false | Normally the command will prompt you for final approval before executing. This will bypass that check. | | `--trap-address` | | The address of the on-chain trap (config) to hydrate. This is the address you see output when you create a new trap or that you will have for your trap in your `drosera.toml` file | | `--dro-amount` | | The amount of DRO you want to hydrate your trap with. Amount is expected in human form (not on-chain form) | #### `bloomboost`[](https://dev.drosera.io/trappers/drosera-cli#bloomboost) Bloom boost the specified trap. This is how you boost a trap's emergency response execution with ETH to entice block builders to include the tx in the mempool. This sends ETH to the traps' `trap_rewards` contract. ##### Args[](https://dev.drosera.io/trappers/drosera-cli#args-4) | Argument | Default | Description | | --- | --- | --- | | `--eth-rpc-url` | | The node used for querying and sending transactions | | `--drosera-rpc-url` | | The url of the seed node to send the trap bytecode to | | `--eth-chain-id` | derived from the ethereum rpc | The chain id | | `--private-key` | | The private key used to sign transactions | | `--drosera-address` | derived from chain id | The address of the main Drosera proxy contract to interact with | | `--non-interactive` | false | Normally the command will prompt you for final approval before executing. This will bypass that check. | | `--trap-address` | | The address of the on-chain trap (config) to boost. This is the address you see output when you create a new trap or that you will have for your trap in your `drosera.toml` file | | `--eth-amount` | | The amount of ETH you want to boost your trap with. Amount is expected in ETHER (not WEI) | #### `dispute`[](https://dev.drosera.io/trappers/drosera-cli#dispute) Dispute an optimistic claim using a ZK proof. A Pinata JWT is required to upload the proof inputs to IPFS. The inputs must be public so the provers can access them. Otherwise local proving can be done on x86 machines. Copy `export PINATA_JWT=` ##### Args[](https://dev.drosera.io/trappers/drosera-cli#args-5) | Argument | Default | Description | | --- | --- | --- | | `--eth-rpc-url` | | The node used for querying and sending transactions | | `--drosera-rpc-url` | | The url of the seed node to send the trap bytecode to | | `--eth-chain-id` | derived from the ethereum rpc | The chain id | | `--private-key` | | The private key used to sign transactions | | `--drosera-address` | derived from chain id | The address of the main Drosera proxy contract to interact with | | `--non-interactive` | false | Normally the command will prompt you for final approval before executing. This will bypass that check. | | `--trap-address` | | The address of the on-chain trap (config) to dispute. This is the `address` you see output when you create a new trap, or that you will have for your trap in your drosera.toml file, or that you will see on the drosera dapp | | `--block-number` | | The block number to perform a dispute on | | `--boundless-rpc-url` | `--eth-rpc-url` | The RPC url for the chain the Boundless market is on (Optional) | | `--boundless-private-key` | `--private-key` | The private key to use for signing a request and submitting the request on-chain (Optional) | | `--boundless-groth16` | false | Whether or not to request a groth16 proof vs. the default merkle inclusion proof. This is required when requesting a proof for a chain that the boundless market is not on. (Optional) | | `--boundless-program-url` | | The url of the guest program to use for generating a proof. Can either be Pinata or an S3 bucket. (Optional) | | `--boundless-blocks-per-minute` | 5 | The number of blocks per minute for the target chain where Boundless is deployed (Optional) | ### `zkclaim`[](https://dev.drosera.io/trappers/drosera-cli#zkclaim) Perform ZK incident response for a trap. A Pinata JWT is required to upload the proof inputs to IPFS. The inputs must be public so the provers can access them. Otherwise local proving can be done on x86 machines. Copy `export PINATA_JWT=` #### Args[](https://dev.drosera.io/trappers/drosera-cli#args-6) | Argument | Default | Description | | --- | --- | --- | | `--eth-rpc-url` | | The node used for querying and sending transactions | | `--drosera-rpc-url` | | The url of the seed node to send the trap bytecode to | | `--eth-chain-id` | derived from the ethereum rpc | The chain id | | `--private-key` | | The private key used to sign transactions | | `--drosera-address` | derived from chain id | The address of the main Drosera proxy contract to interact with | | `--non-interactive` | false | Normally the command will prompt you for final approval before executing. This will bypass that check. | | `--trap-address` | | The address of the on-chain trap (config) to claim. This is the `address` you see output when you create a new trap, or that you will have for your trap in your drosera.toml file, or that you will see on the drosera dapp | | `--block-number` | | The block number to perform claim | | `--boundless-rpc-url` | `--eth-rpc-url` | The RPC url for the chain the Boundless market is on (Optional) | | `--boundless-private-key` | `--private-key` | The private key to use for signing a request and submitting the request on-chain (Optional) | | `--boundless-groth16` | false | Whether or not to request a groth16 proof vs. the default merkle inclusion proof. This is required when requesting a proof for a chain that the boundless market is not on. (Optional) | | `--boundless-program-url` | | The url of the guest program to use for generating a proof. Can either be Pinata or an S3 bucket. (Optional) | | `--boundless-blocks-per-minute` | 5 | The number of blocks per minute for the target chain where Boundless is deployed (Optional) | #### `kick-operator`[](https://dev.drosera.io/trappers/drosera-cli#kick-operator) Kick one or more operators from a trap so they are no longer opted in. If you do not also remove the operator from the trap's whitelist, they will simply be able to opt back in. ##### Args[](https://dev.drosera.io/trappers/drosera-cli#args-7) | Argument | Default | Description | | --- | --- | --- | | `--eth-rpc-url` | | The node used for querying and sending transactions | | `--drosera-rpc-url` | | The url of the seed node to send the trap bytecode to | | `--eth-chain-id` | derived from the ethereum rpc | The chain id | | `--private-key` | | The private key used to sign transactions | | `--drosera-address` | derived from chain id | The address of the main Drosera proxy contract to interact with | | `--non-interactive` | false | Normally the command will prompt you for final approval before executing. This will bypass that check. | | `--trap-address` | | The address of the on-chain trap (config) to kick operators from. This is the `address` you see output when you create a new trap, or that you will have for your trap in your drosera.toml file, or that you will see on the drosera dapp | | `--operators` | | The address of one or more operators to kick from the given trap. Ex: --operators 0x70997970C51812dc3A010C7d01b50e0d17dc79C8 0xa85233C63b9Ee964Add6F2cffe00Fd84eb32338f | #### `set-bloomboost-limit`[](https://dev.drosera.io/trappers/drosera-cli#set-bloomboost-limit) Update the percentage of a trap's ETH balance that can be used for bloom boosting a response action. Default value is 0 bps (0%). ##### Args[](https://dev.drosera.io/trappers/drosera-cli#args-8) | Argument | Default | Description | | --- | --- | --- | | `--eth-rpc-url` | | The node used for querying and sending transactions | | `--drosera-rpc-url` | | The url of the seed node to send the trap bytecode to | | `--eth-chain-id` | derived from the ethereum rpc | The chain id | | `--private-key` | | The private key used to sign transactions | | `--drosera-address` | derived from chain id | The address of the main Drosera proxy contract to interact with | | `--non-interactive` | false | Normally the command will prompt you for final approval before executing. This will bypass that check. | | `--trap-address` | | The address of the on-chain trap (config) to kick operators from. This is the `address` you see output when you create a new trap, or that you will have for your trap in your drosera.toml file, or that you will see on the drosera dapp | | `--limit` | | The new bloom boost limit as a percentage in basis points i.e 10000 bps = 100%, 3100 bps = 31%. Default is 0 bps (0%) | #### `liveness`[](https://dev.drosera.io/trappers/drosera-cli#liveness) Get liveness data for a trap, showing recent results computed by opted in operators. ##### Args[](https://dev.drosera.io/trappers/drosera-cli#args-9) | Argument | Default | Description | | --- | --- | --- | | `--eth-rpc-url` | | The node used for querying and sending transactions | | `--drosera-rpc-url` | | The url of the seed node to send the trap bytecode to | | `--eth-chain-id` | derived from the ethereum rpc | The chain id | | `--private-key` | | The private key used to sign transactions | | `--drosera-address` | derived from chain id | The address of the main Drosera proxy contract to interact with | | `--trap-address` | | The address of the on-chain trap (config) to query for liveness data. This is the `address` you see output when you create a new trap, or that you will have for your trap in your `drosera.toml` file, or that you will see on the drosera dapp | | `--block-number` | current block number - 1 | (optional) Specifies at which historical block to fetch trap results from. Historical data is only maintained for a limited period of time so recent blocks may have data, but further blocks data may not exist anymore | #### `recover`[](https://dev.drosera.io/trappers/drosera-cli#recover) Reconstruct a trapper's `drosera.toml` from on-chain state data, using the provided private key. ##### Args[](https://dev.drosera.io/trappers/drosera-cli#args-10) | Argument | Default | Description | | --- | --- | --- | | `--eth-rpc-url` | | The node used for querying and sending transactions | | `--private-key` | | The private key used to find trap data | | `--eth-chain-id` | derived from the ethereum rpc | (Optional) The chain id | | `--drosera-address` | derived from chain id | (Optional) The address of the main Drosera proxy contract to interact with | | `--write-path` | ./recovered\_drosera.toml | (Optional) The path to write the recovered drosera.toml file to, ex `--write-path /path/to/drosera.toml`. If not provided, the CLI will write the file to the current working directory and call it recovered\_drosera.toml. | --- # Dryrunning a Trap – Docs [Skip to content](https://dev.drosera.io/trappers/dryrunning-a-trap#vocs-content) Search... [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) Menu Chevron Down Menu Dryrunning a Trap On this page Chevron Right Ideally you would be able to test your trap with real block/state data before deploying it for real, on-chain. Well, with the `dryrun` command you can. In normal trap operation, a trap will be "monitored" by one or more opted-in operators, but with the `dryrun` command you can easily test two lifecycles (a bootstrap and a normal lifecycle) of this same process on your local machine with what is for all intents and purposes, a locally spun-up ad-hoc operator. Under The Hood[](https://dev.drosera.io/trappers/dryrunning-a-trap#under-the-hood) ------------------------------------------------------------------------------------- The lifecycle will be performed with block(s) pulled from your specified evm endpoint, `ethereum_rpc` in your `drosera.toml` config file. The number of blocks pulled is determined by your configured `block_sample_size` (also `drosera.toml`) for the trap. ### Lifecycle[](https://dev.drosera.io/trappers/dryrunning-a-trap#lifecycle) 1. The `block_sample_size` latest blocks are processed by the trap's `collect` function: * **Bootstrap Lifecycle**: For the first lifecycle, the system starts from scratch with no cached data. It fetches each block from your RPC endpoint and runs the `collect` function on it. During this process, account and slot data are fetched one by one, as needed during trap (solidity contract) execution. All collect results are then cached for future use. * **Runtime Lifecycle**: For subsequent lifecycles, the system has cached results for `collect` calls on previous blocks. This way it only needs to run `collect` for the one new block. This one `collect` also runs faster as potential needed account and slot data are pre-fetched in a batch call, so the trap runs much faster due to significantly less RPC calls being made. 2. The outputs of the `collect` calls are passed as input to one call of the `should_respond` function. 3. `should_respond` will return a value of `false` for do nothing, or `true` for execute the specified `response_function` (`drosera.toml`). You've now been able to verify that your trap is functioning end-to-end, as if it was already deployed to the Drosera network. ### Example[](https://dev.drosera.io/trappers/dryrunning-a-trap#example) Command: `drosera dryrun` ![dryrun example run](https://dev.drosera.io/img/dryrun_example_run.png) This trap has a `block_sample_size` of 3 in this example, so each lifecycle performs 3 collects. The 1st (bootstrap) lifecycle starts with no cached collect results so it has to perform all of the computation and block fetching, resulting in a longer lifecycle time of 5.25 seconds compared to the 2nd lifecycle's 2.42 seconds. In the 2nd (normal) lifecycle, it speeds through collects for blocks 4,203,641 and 4,203,642 because the collect results for those blocks were already computed in the previous lifecycle, saving RPC network call time and `collect` computation time. Only until it reaches the new block of 4,203,643 that it hasn't encountered before, does it have to fetch it from the RPC and run the `collect` function on it. So the bootstrap lifecycle always takes longer than normal lifecycles. Theory-crafting[](https://dev.drosera.io/trappers/dryrunning-a-trap#theory-crafting) --------------------------------------------------------------------------------------- With the optional `--block-number` argument, `dryrun` can be used to test traps on past state. This allows anything from more robust testing of a trap, all the way to verifying that a trap successfully catches a past exploit. An excellent addition to the security researcher tool belt. How To Run[](https://dev.drosera.io/trappers/dryrunning-a-trap#how-to-run) ----------------------------------------------------------------------------- Copy `drosera dryrun --block-number ` where `--block-number` is optional. Without, it defaults to the current block number. Lifecycle Limitations[](https://dev.drosera.io/trappers/dryrunning-a-trap#lifecycle-limitations) --------------------------------------------------------------------------------------------------- With traps, you have significantly more gas to work with than a contract on-chain. Blocks on Ethereum currently have a total `block.gasLimit` of ~30 million gas units. So the sum of gas used by all transactions in a block cannot excede this number. In another stratosphere, Drosera is configured to allow up to 1 billion gas units per `collect` function and 1 billion gas units per `shouldRespond` function. This means that one trap lifecycle with a `block_sample_size` of 1 could use up to 2 billion gas units, or approximately 66x more gas than what can fit in an entire Ethereum block. But, with great power comes great responsibility. Ethereum blocks average about 12 seconds per block, and so in order for a trap to retain its ability of responding in the next block after the configured condition is detected (`shouldRespond` returns true), it needs to be able to be executed within a few seconds by the [recommended system requirements](https://dev.drosera.io/operators/installation#recommended-system-requirements) . If the trap takes too long to execute on recommended spec operator hardware, then the operators running the trap will struggle or be unable to keep up with Ethereum block times and begin falling further and further behind. ![dryrun long running warning](https://dev.drosera.io/img/dryrun_over_time_warning.png) Therefore `dryrun` has a safety check built in. If a trap's normal lifecycle (>= 2nd lifecycle) takes longer than a recommended upper time limit, it will emit a warning. `dryrun` is running on your local computer, so if your computer specs are equal to or lower than the recommended operator specs, this trap (when deployed) may struggle or entirely fail to keep up with on-chain blocks, thus falling behind and either reducing the effectivness of the trap or defeating its security use case entirely. If your computer specs are better than the recommended operator specs, and `dryrun` yields this warning, the trap will most certainly have the previously mentioned issues when deployed. Additionally, for certain trap designs querying many accounts/slots, RPC latency may be a factor at play here as well. --- # Kicking an Operator – Docs [Skip to content](https://dev.drosera.io/trappers/kicking-an-operator#vocs-content) Search... [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) Menu Chevron Down Menu Kicking an Operator On this page Chevron Right If you would like to remove an operator from the set of operators running/monitoring your trap, you can kick them with the `kick-operator` command. ### Lifecycle[](https://dev.drosera.io/trappers/kicking-an-operator#lifecycle) #### Operators[](https://dev.drosera.io/trappers/kicking-an-operator#operators) 1. Operator is whitelisted as either a Drosera [protocol-level whitelisted operator](https://dev.drosera.io/trappers/private-traps#protocol-level-operators) or a [trap-level whitelisted operator](https://dev.drosera.io/trappers/private-traps#trap-level-operators) that the trap owner has specifically added to the trap's `drosera.toml` `whitelist` field, and has updated the trap on-chain with the `apply` CLI command 2. The operator can opt in because they are whitelisted #### Trap Owner[](https://dev.drosera.io/trappers/kicking-an-operator#trap-owner) 1. If you no longer want an operator to monitor/run your trap, here are the steps to take. First... * If the operator is a protocol-level operator, you'll need to know their address. If the trap is public, they won't be in the trap's `whitelist`. * If the operator is a trap-level operator that you previously added to the trap's `whitelist`, remove their address from the trap's `whitelist` and run the `apply` command to update the trap on-chain. 2. Second, you must run the `kick-operator` CLI command with the operator's address and the trap address to effectively opt out the operator from your trap. If you only kick a trap-level operator, but don't remove them from the whitelist also, the operator can just opt in again. To kick an operator from your trap, simply run: Copy `drosera kick-operator --trap-address
--operators ` You can pass one or more operator addresses, separated by spaces, starting with "0x" --- # Setting Bloomboost Percentage – Docs [Skip to content](https://dev.drosera.io/trappers/setting-bloomboost-percentage#vocs-content) Search... [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) Menu Chevron Down Menu Setting Bloomboost Percentage On this page Chevron Right This command pairs with the `bloomboost` CLI command. You can run the `set-bloomboost-limit` CLI command at any time. When your trap is triggered and the response function is called, if the bloomboost limit is set above 0%, then that percentage of the the trap config's trap-reward contract ETH balance will be sent to the block builder to incentivize inclusion of the transaction in the current block being built (important especially in times of high congestion and fees). The `set-bloomboost-limit` CLI command updates this percentage. ### Example[](https://dev.drosera.io/trappers/setting-bloomboost-percentage#example) 1. Trap (trap-reward contract) is bloomboosted with 10 ETH 2. Trap gets triggered at some point and the gas cost is 1 ETH 3. Operator pays the 1 ETH gas and at the end of the tx is reimbursed for the 1 ETH plus a little extra 4. The trap-reward contract now has 9 ETH left after gas payment 5. 50% (5000 BPS) bloom boost limit means 4.5 ETH is sent to block proposer (50% of 9 ETH) ![bloom boost flow chart](https://dev.drosera.io/img/bloom_boost_flow.png) This gives you more granular control over your bloomboost configuration. For traps monitoring higher value/more critical contracts, you can boost the trap with more ETH and/or set a higher percentage here to further boost the traps priority, which is especially important during turbulent market conditions. Copy `drosera set-bloomboost-limit --trap-address
--limit ` Where `limit` is an integer between 0 and 10000 and it is a percentage expressed in basis points (BPS). To convert a percentage to BPS you can take your percentage (with up to two decimal places) and simply multiply it by 100 i.e. 51.02% \* 100 = 5102 BPS. --- # Recover your drosera.toml File – Docs [Skip to content](https://dev.drosera.io/trappers/recover-drosera-toml#vocs-content) Search... [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) Menu Chevron Down Menu Recovering your drosera.toml File On this page Chevron Right The `drosera.toml` file is your local reference to all of your traps (typically under one keypair). It specifies how you want them configured, the paths to the compiled trap code on your local computer, the response functions and contracts, the Ethereum RPC you choose to use, etc. So this file is important, but life can happen and the file may be deleted, corrupted, etc by accident or no fault of your own. In this case, you can use the trapper CLI `recover` command. This will reconstruct the majority of a `drosera.toml` file, using on-chain state data, given a private key. It is a lossy reconstruction. It does not reconstruct the file 100% the way it was. After the file is recovered, you will need to identify each trap in the file and re-specify the `path` variable to where the compiled trap code is on your local computer, because that data is not stored on-chain. This command pulls all of the trap data from on-chain that is owned by the specified `--private-key`. If you have separated multiple traps in multiple different `drosera.toml` files, all created using the same private key, this command will recover all of them into one file. Finally, any traps you deployed with a different private key will not be pulled down with this command. For traps created with a different private key you will need to run the command again for each sepearate private key. Recover[](https://dev.drosera.io/trappers/recover-drosera-toml#recover) -------------------------------------------------------------------------- Copy `drosera recover --eth-rpc-url --private-key 0x` Once you have the file and have re-specified the `path` fields for each trap with the location of their compiled trap code, you can then rename the file to the name the CLI looks for automatically which is `drosera.toml`. --- # Getting Liveness Data – Docs [Skip to content](https://dev.drosera.io/trappers/getting-liveness-data#vocs-content) Search... [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) Menu Chevron Down Menu Getting Liveness Data On this page Chevron Right This command allows you to check current liveness of operators opted in to a trap. Liveness[](https://dev.drosera.io/trappers/getting-liveness-data#liveness) ----------------------------------------------------------------------------- At a high level, a trap relies on operators monitoring (`collect` & `shouldRespond` trap functions) it every block. In a centralized service you might be running all infrastructure in-house and maintain everything to a high degree of uptime. However, Drosera is a decentralized system and therefore a trap typically relies on outside entities running and maintaining operators to keep the trap live every block. With Drosera, you have the option to run all of your own operators, but many trappers will opt to use pre-existing operators, such as protocol-level whitelisted operators. In this 2nd case, you may want to monitor the "performance" or monitoring uptime of operators on your trap. In a perfect scenario, every operator opted in to your trap would execute and broadcast the result of the execution to the trap's p2p network every block. In the real world this will likely not be the case though. Some operators may miss trap execution for certain blocks here and there due to network hiccups, etc. Rarely, this may be acceptable, but if it happens often, this operator may not be considered reliable anymore and the trap owner can make the executive decision to kick said operator from it's operator set. Even worse, an operator could simply go down completely and never come back online. In addition to the `liveness` command, you can also get a higher level graphical view of liveness data on individual trap pages on [Drosera's dapp](https://app.drosera.io/) ![Drosera dapp liveness](https://dev.drosera.io/img/drosera-dapp-liveness.png) **To summarize**: Liveness encapsulates the idea that, for the set of operators opted in to a given trap, how active or not are they in submitting trap result attestations every block. Example[](https://dev.drosera.io/trappers/getting-liveness-data#example) --------------------------------------------------------------------------- Running the below command with only a trap hash defined will yield the trap results from operators over the number of blocks defined in the trap's `block_sample_size`, ranging from the current block - 1 and going down `block_sample_size` blocks. It is "-1" because for the current block, operator attestations are still moving around over the trap's p2p network and therefore it may yield an incomplete picture. This gives time for network traffic to arrive. In this example: * The current block number is 35 * `block_sample_size` = 2 * Therefore trap results for 2 blocks are returned that range from blocks 33-34 If you additionally include an optional block number(`--block-number`), you can look at recent historical trap results at that point in time. Copy `drosera liveness --trap-address 0xEd3a7f81e91EEB1702274AA4b7e2acc7b0D20f4F` Below is the example output from running this command. It fetched liveness data for the latest block - 1, which is `block_number` 35 that can be seen in the trap result from each operator. This trap has two operators opted in and we see both of them have attested their result of executing the given trap for `block_number`'s 33 and 34, as ideally expected. Importantly, here you can find * `should_respond`: Whether or not the operator computed that the trap's emergency response function should be called * `response_data`: Data returned by the `shouldRespond` function to be passed to the emergency response function if `should_respond` is `true` * `operator`: The address of the operator that authored this trap result * `non_signers`: An operator expects to receive trap results from all other operators under the trap. If the operator didn't receive a trap result from another operator, that operator's address will be counted here as a non-signer. Copy `Liveness Data: [ [ TrapResultWithOutput { trap_address: 0xfc4df3332bb0379ccd79e1d0874a6fa5196c1aba, block_number: 33, block_hash: 0x7f0bd423953a3b8448d9d23a79751bbbf339a05ada4fe9a42b26770a1826b034, should_respond: false, response_data: 0x0000000000000000000000000000000000000000000000000000000000000021, trap_hash: 0x73cccd382abf097c44e206d6541ef1ff862c7bcf55c85a56400de0435aead4c0, collect_output: 0x00000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000000a0000000000000000000000000000000000000000000000000000000000000021, operator: 0x70997970c51812dc3a010c7d01b50e0d17dc79c8, failure: false, failure_reason: "", non_signers: [], }, TrapResultWithOutput { trap_address: 0xfc4df3332bb0379ccd79e1d0874a6fa5196c1aba, block_number: 33, block_hash: 0x7f0bd423953a3b8448d9d23a79751bbbf339a05ada4fe9a42b26770a1826b034, should_respond: false, response_data: 0x0000000000000000000000000000000000000000000000000000000000000021, trap_hash: 0x73cccd382abf097c44e206d6541ef1ff862c7bcf55c85a56400de0435aead4c0, collect_output: 0x00000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000000a0000000000000000000000000000000000000000000000000000000000000021, operator: 0x9d487a765a059f922b4cc4a9492d5cb8e1f33bc1, failure: false, failure_reason: "", non_signers: [], }, ], [ TrapResultWithOutput { trap_address: 0xfc4df3332bb0379ccd79e1d0874a6fa5196c1aba, block_number: 34, block_hash: 0xc3836f31c081d4e0a373b28cca82c6dcbda1dd2070cd48fe74c1a94dc75dde8a, should_respond: false, response_data: 0x0000000000000000000000000000000000000000000000000000000000000022, trap_hash: 0x73cccd382abf097c44e206d6541ef1ff862c7bcf55c85a56400de0435aead4c0, collect_output: 0x00000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000000a0000000000000000000000000000000000000000000000000000000000000022, operator: 0x70997970c51812dc3a010c7d01b50e0d17dc79c8, failure: false, failure_reason: "", non_signers: [], }, TrapResultWithOutput { trap_address: 0xfc4df3332bb0379ccd79e1d0874a6fa5196c1aba, block_number: 34, block_hash: 0xc3836f31c081d4e0a373b28cca82c6dcbda1dd2070cd48fe74c1a94dc75dde8a, should_respond: false, response_data: 0x0000000000000000000000000000000000000000000000000000000000000022, trap_hash: 0x73cccd382abf097c44e206d6541ef1ff862c7bcf55c85a56400de0435aead4c0, collect_output: 0x00000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000000a0000000000000000000000000000000000000000000000000000000000000022, operator: 0x9d487a765a059f922b4cc4a9492d5cb8e1f33bc1, failure: false, failure_reason: "", non_signers: [], }, ] ]` Command[](https://dev.drosera.io/trappers/getting-liveness-data#command) --------------------------------------------------------------------------- Copy `drosera liveness --trap-address
--block-number ` Where `--block-number` is optional --- # Registration – Docs [Skip to content](https://dev.drosera.io/operators/register#vocs-content) Search... [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) Menu Chevron Down Menu Register On this page Chevron Right To run the Drosera Operator Node, you must first register as an Operator. This process involves registering a public BLS public key with the Drosera contracts. This can be achieved by running the following command: Copy `drosera-operator register --eth-rpc-url --eth-private-key ` The BLS public key is derived using the operator's private key. The public key is used to sign attestations and then aggregated to reach consensus on the state of the network. --- # Run the Node – Docs [Skip to content](https://dev.drosera.io/operators/run-operator#vocs-content) Search... [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) Menu Chevron Down Menu Run Operator On this page Chevron Right Running the Drosera Operator Node is a simple process. This guide will walk you through the steps to run the Operator Node, enabling you to begin executing Traps and earning rewards. The Operator Node can quickly be started using the following command: Copy `drosera-operator node` If the Operator Node is configured correctly, you should see the following output: Copy `INFO drosera_operator::node: Operator Node successfully spawned!` Configuration[](https://dev.drosera.io/operators/run-operator#configuration) ------------------------------------------------------------------------------- The Operator Node can be configured using CLI arguments, a toml config file, or with environment variables. A combination of either can also be used. The order of precedence is as follows: * Command line arguments * TOML configuration file `./drosera.toml` * Environment variables / .env file ### CLI Arguments[](https://dev.drosera.io/operators/run-operator#cli-arguments) | Argument | Default | Description | | --- | --- | --- | | `--eth-rpc-url` | | The node used for querying and sending transactions | | `--eth-backup-rpc-url` | | A backup Ethereum RPC if the primary RPC node becomes unresponsive. This arg is optional | | `--eth-chain-id` | derived from eth rpc | The chain id | | `--eth-private-key` | | The private key used to sign transactions | | `--drosera-address` | derived from chain id | The address of the main Drosera proxy contract to interact with | | `--gas-reimbursement-required` | false | Whether or not gas reimbursement is required to submit a claim. Omitting this flag will default to false. | | `--db-file-path` | `./data/drosera.db` | The path to the database file to use for persistence when not in dev mode | | `--dev-mode` | `false` | Runs the Operator node without persisting data | | `--block-polling-interval-ms` | `1000` | The number of milliseconds to wait between polling for new blocks | | `--disable-dnr-confirmation` | false | "Disables the DNR confirmation. Only set this if you are running this node behind a NAT, and you are receiving a 'Failed to confirm DNR' error message. Verify the public address setting is correct and any firewall walls are opened for the configured ports before turning this setting on. | | `--listen-address` | `0.0.0.0` | The network interface to bind the Operators RPC and P2P server to | | `--log-level` | `info` | The log level for the Operator Node (info, warn, error, trace, debug). You can also specify directives similar to the `RUST_LOG` env variable. e.g. `"info,drosera_services::network::p2p=debug"`. | | `--log-format` | `full` | The log format for the Operator Node (full, compact, pretty, json) | | `--log-output` | `stdout` | The log output for the Operator Node (stdout, file) | | `-v` | | The verbosity level to use for instrumentation. -v = warn, -vv = info, -vvv = debug, -vvvv = trace | | `--otel-export-endpoint` | `""` | The OpenTelemetry Collector endpoint to send metrics and trace data too | | `--otel-export-metadata` | `{}` | The OpenTelemetry Collector metadata to send with metrics and trace data. e.g. Authorization Headers | | `--otel-resource-attributes` | `""` | Add resource attribute labels to all collected OpenTelemetry metrics, traces and logs. e.g. `"operator_address=0x530719E8fe572C909945Deb045e491865FF2bab0,operator_name=cobra"` | | `--network-external-p2p-address` | | The external address to reach the Operator node at for p2p communications | | `--network-external-rpc-address` | `${network-external-p2p-address}` | The external address to reach the Operator node's rpc server. Useful for proxies. Default is the network external p2p address. If provided and starts with either http or https, the value will be used as is by the seed node to retrieve liveness data. Otherwise, if a dns or ip is provided without a protocol, http is assumed and the server port will be appended. | | `--network-p2p-port` | `31313` | The TCP port to bind the P2P server to | | `--network-secret-key` | `--eth-private-key` | The secret key used to sign messages sent over the network and generating a peer id | | `--server-port` | `31314` | The TCP port to bind the rpc server to | | `--server-concurrency-limit` | `100` | The maximum number of concurrent requests the RPC server can handle | | `--server-connection-limit` | `500` | The maximum number of concurrent connections the RPC server can handle | | `--server-requests-per-second` | `10` | The maximum number of requests per second the RPC server accepts before rate limiting. Only applicable if rate limit by ip is turned on. | | `--server-rate-limit-by-ip` | `true` | Enable rate limiting by IP address | | `--server-burst-size` | `10` | The maximum number of requests that can be bursted before rate limiting within the requests per second window. Only applicable if rate limit by ip is turned on. | | `--help` | | Display the help menu | | `--version` | | Display the version of the Operator Node | The `--network-external-p2p-address` is required for the Operator to be discoverable by other nodes. The public address can either be an IP address or a domain name. If a domain name is used, the domain must resolve to the public IP address of the Operator. ### TOML Configuration[](https://dev.drosera.io/operators/run-operator#toml-configuration) The Operator Node can be configured using a TOML configuration file. The configuration file should be named `drosera.toml` and placed in the root directory of the Operator Node. The configuration file should be formatted as follows: Copy `db_file_path = "./data/drosera.db" block_polling_interval_ms = 1000 dev_mode = false listen_address = "127.0.0.1" [eth] rpc_url = "http://localhost:8545" backup_rpc_url = "http://localhost:8546" [network] p2p_port = 31313 secret_key = "" # Required, provide your own external_p2p_address = "" # Required, provide your own external_rpc_address = "" # Optional if different from external_p2p_address [server] port = 31314 concurrency_limit = 100 connection_limit = 500 requests_per_second = 10 rate_limit_by_ip = false burst_size = 10 [instrumentation] log_level = "info" log_format = "full" log_out = "stdout" # Requires monitoring setup running. Check the Operator "Monitoring" section of the docs # otel_export_endpoint = "http://localhost:4317" # otel_export_metadata = { authorization = "Basic ..." } # otel_resource_attributes = { operator_address = "0x530719E8fe572C909945Deb045e491865FF2bab0", operator_name = "cobra" }` ### Environment Variables[](https://dev.drosera.io/operators/run-operator#environment-variables) All of the CLI arguments can be set as environment variables. The environment variables should be prefixed with `DRO__` and use uppercase letters. For example, the `--eth-rpc-url` argument would be set as `DRO__ETH__RPC_URL`. The `__` indicates a new level in the name spacing. Example configuration: Copy `export DRO__ETH__PRIVATE_KEY=0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 export DRO__ETH__RPC_URL=http://localhost:8545 export DRO__ETH__BACKUP_RPC_URL=http://localhost:8546 export DRO__DB_FILE_PATH=./data/drosera.db export DRO__BLOCK_POLLING_INTERVAL_MS=1000 export DRO__SERVER__PORT=31314 export DRO__NETWORK__P2P_PORT=31313 export DRO__INSTRUMENTATION__LOG_LEVEL=info export DRO__INSTRUMENTATION__OTEL_EXPORT_ENDPOINT=http://localhost:4317` ### Private Key[](https://dev.drosera.io/operators/run-operator#private-key) The operators `private_key` that is actually used for signing ethereum transactions, is not allowed in the `drosera.toml` file for security reasons. It can be set as an environment variable or passed as a CLI argument in applicable commands. Setting as an environment variable is the easiest method. --- # Executing Traps – Docs [Skip to content](https://dev.drosera.io/operators/executing-traps#vocs-content) Search... [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) Menu Chevron Down Menu Executing Traps On this page Chevron Right Executing traps is a crucial part of the Drosera ecosystem. Traps are smart contracts that define the conditions for detecting on-chain invariants and performing on-chain responses. Operators are responsible for executing Traps and performing on-chain response actions, ensuring the security and stability of the network. Operators can opt into a Trap to gain permission to execute it and earn rewards. Once opted in, the Operator gains access to the off-chain Trap and the current peers in the network. This allows them to actively participate in monitoring and evaluating every new block based on the conditions set by the Trap. In the event that the conditions of a Trap are met, the Operator will promptly execute the on-chain response function. This swift action helps to mitigate potential threats and exploits. To opt in into a trap, the following steps are required: 1. Register as an Operator 2. Get whitelisted by the Drosera team. (Permission-less operators will be available in the future) 3. Run the Drosera Operator Node 4. Opt into the Trap Opting into a Trap[](https://dev.drosera.io/operators/executing-traps#opting-into-a-trap) -------------------------------------------------------------------------------------------- You can opt into a Trap by running the following command: Copy `drosera-operator optin --eth-rpc-url --eth-private-key --trap-config-address ` The trap-config-address is the address of the Trap Config contract that you want to opt into. The Trap Config contract holds a hash of the Trap contract and the address of the on-chain response function. It is used to help coordinate the execution of the Trap and the on-chain response function with Operators as well as holding them accountable for doing so. **The config address can be found on Drosera's website or by querying the Drosera contract**. After successfully opting into a Trap, you should see the following output: Copy `INFO drosera_operator::opt_in: Opted in successfully!` If your Operator node has been running, it will pick up the opt in event and start executing the Trap. You can monitor the execution of the Trap by checking the logs of the Operator node. If your Operator node is not running, it will begin executing the Trap once it is started. The Operator node can opt into multiple Traps and will be rewarded for each based on the Hydration streams configured by the Trap creator. Opting Out of a Trap[](https://dev.drosera.io/operators/executing-traps#opting-out-of-a-trap) ------------------------------------------------------------------------------------------------ To opt out of a Trap, you can run the following command: Copy `drosera-operator optout --eth-rpc-url --eth-private-key --trap-config-address 0x` After successfully opting out of a Trap, you should see the following output: Copy `INFO drosera_operator::opt_out: Opted out successfully!` The Operator node will stop executing the Trap and will no longer be rewarded for its execution. Root Operators[](https://dev.drosera.io/operators/executing-traps#root-operators) ------------------------------------------------------------------------------------ If you plan on running multiple operators, you may want to take advantage of setting up a root operator. This requires a little bit more work to setup at the beginning, but saves time after that when it comes to claiming earned funds from hydration streams. If, for example, you run ten operators, instead of having to claim rewards ten different times, you can set them up with a root operator and all of the rewards for all 10 operators will go to the account of the root operator. Only one claim required now. There are two ways to set up a root operator for an operator 1. When registering the operator, specify the optional `--root-operator-address` with the address of your desired account Copy `drosera-operator register --eth-rpc-url --eth-private-key --root-operator-address 0x` 2. If your operator is already registered, you can update the root operator address with the Operator CLI `update-root-operator` command. You can set the root operator for a list of operators (addresses separated by commas). Copy `drosera-operator update-root-operator --eth-rpc-url --eth-private-key --operator-addresses 0x,0x,0x --root-operator-address 0x` --- # Testnet Guide – Docs [Skip to content](https://dev.drosera.io/operators/testnet-guide#vocs-content) Search... [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) Menu Chevron Down Menu Testnet Guide On this page Chevron Right This guide is for the Protocol level Whitelisted operators. Drosera operates on the Hoodi testnet. This guide will walk through the steps to get your Operator node onboarded into Drosera's Testnet. It is recommended a new ECDSA key-pair is generated for the Operator node and is funded with testnet ETH. You can obtain testnet ETH from the following Hoodi Testnet Faucets: * [PoWFaucet](https://hoodi-faucet.pk910.de/) * [Stakely](https://stakely.io/faucet/ethereum-hoodi-testnet-eth) * [Quicknode](https://faucet.quicknode.com/ethereum/hoodi) 1. Download and install the latest release of the Drosera Operator Node by following the instructions in the [Installation](https://dev.drosera.io/operators/installation) guide. 2. Configure the Operator node by following the instructions in the [Run the Node](https://dev.drosera.io/operators/run-operator) guide. Testnet Operators will need to use an RPC endpoint for a Hoodi Ethereum node. 3. Register your Operator node by following the instructions in the [Register](https://dev.drosera.io/operators/register) guide. 4. Set our Drosera team managed account as the root operator for your operator: Copy `drosera-operator update-root-operator --eth-rpc-url --eth-private-key --operator-addresses 0x --root-operator-address 0xd98e2ae62de96ab1d39cfcaef134692a507d38f3` 5. Start the Operator node by running the following command: Copy `drosera-operator node --eth-rpc-url --eth-private-key --listen-address 0.0.0.0 --network-p2p-port 31313 --network-external-p2p-address --server-port 31314` 6. That's it! Your Operator node is now onboarded into Drosera's Testnet. You can monitor the execution of Traps by checking the logs of the Operator node. ### The `drosera-operator` can also be run as a docker container.[](https://dev.drosera.io/operators/testnet-guide#the-drosera-operator-can-also-be-run-as-a-docker-container) [drosera-operator](https://github.com/orgs/drosera-network/packages/container/package/drosera-operator) : `ghcr.io/drosera-network/drosera-operator:latest` Please follow the [Run with Docker](https://dev.drosera.io/operators/run-with-docker) guide to run the operator using Docker. --- # Private Traps – Docs [Skip to content](https://dev.drosera.io/trappers/private-traps#vocs-content) Search... [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) Menu Chevron Down Menu Private Traps On this page Chevron Right The default for a trap is to be public (i.e. `private_trap = false` in your `drosera.toml`). In this configuration, the only operators who can opt in to your trap and run it are protocol-level operators. ### Protocol-Level Operators[](https://dev.drosera.io/trappers/private-traps#protocol-level-operators) These operators are run by entities hand-picked by the Drosera team that are known and respected node runners in the blockchain space. When you create a trap, automatically, there will already be a set of operators available that are professionally managed with high uptime, as you would expect at an enterprise level. If your trap is public, all of these protocol-level operators have the ability to opt in and run your trap. However, if you set your trap to private (`private_trap = true`), then none of these protocol-level operators will be able to opt in unless you explicitly add their operator address to the trap's `whitelist`. ### Trap-Level Operators[](https://dev.drosera.io/trappers/private-traps#trap-level-operators) For some, only protocol-level operators will be sufficient. Others may want to exclusively run their own infrastructure, or let one of their friends (who loves running nodes but is not a protocol-level whitelisted operator) participate in monitoring their trap. In this case, they can simply add the address of the desired operator to the trap's whitelist and update the trap on-chain. Then the non-protocol-level whitelisted operator will be able to opt in. | | **protocol-level operators** | **trap-level operators** | | --- | --- | --- | | **Trap is public** | All protocol-level operators can opt in to the trap | Can only opt in if they are explicitly added to the trap whitelist | | **Trap is private** | Can only opt in if they are explicitly added to the trap whitelist | Can only opt in if they are explicitly added to the trap whitelist | This allows flexible control for who is allowed to run your trap. You can have plug and play, professionally run operators, or exclusively run your own operators, or utilize some of both. The choice is yours. --- # Monitoring – Docs [Skip to content](https://dev.drosera.io/operators/metrics#vocs-content) Search... [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) Menu Chevron Down Menu Metrics On this page Chevron Right The Operator Node can be configured to send Opentelemetry metrics, logs and traces to an OpenTelemetry Collector. The OpenTelemetry Collector can then be configured to send the metrics to a variety of backends such as Prometheus, Grafana, or other monitoring tools. To configure the Operator Node to send metrics to an OpenTelemetry Collector, you can use the following CLI arguments: Copy `drosera-operator node --otel-export-endpoint --otel-export-metadata --otel-resource-attributes ` Description of the CLI arguments can be found on the configuration section of the [Run the Node](https://dev.drosera.io/operators/run-operator#configuration) page. Logging[](https://dev.drosera.io/operators/metrics#logging) -------------------------------------------------------------- If running the Operator Node as a systemd service, all logs will be persisted on the machine and will consume storage space. To avoid this, you can configure the otel export endpoint to send logs to a remote logging service and send the stdout logs to `/dev/null` when starting the the Operator Node. This will prevent logs from being stored on the machine. Copy `drosera-operator node --otel-export-endpoint --log-output stdout > /dev/null` Metrics[](https://dev.drosera.io/operators/metrics#metrics) -------------------------------------------------------------- The Operator Node collects the following metrics: * `drosera_process_cpu_usage`: The CPU usage of the Operator Node process * `drosera_process_disk_space_usage`: The disk space usage of the Operator Node process * `drosera_process_memory_usage`: The memory usage by the Operator Node process * `total_memory`: The total memory available on the system * `execute_trap_duration`: The duration of time it takes to execute a Trap * `attestation_consensus_duration`: The duration of time it takes to reach consensus on an attestation of a Trap result * `connected_peer_count`: The number of peers sending messages to the Operator Node * `expected_peer_count`: The number of peers the Operator Node should be receiving messages from * `eth_balance`: The balance of the Operator Node's Ethereum account Resource Attributes[](https://dev.drosera.io/operators/metrics#resource-attributes) -------------------------------------------------------------------------------------- Attributes can be added to all collected OpenTelemetry metrics, traces and logs. For example, to add the operator address and name to all metrics, traces and logs, you can use the `--otel-resource-attributes` CLI argument: Copy `drosera-operator node --otel-resource-attributes "operator_address=0x530719E8fe572C909945Deb045e491865FF2bab0,operator_name=cobra"` To visualize the metrics, logs, and traces exported by the Operator Node, you can use the following monitoring stack: [https://github.com/drosera-network/operator-monitoring-stack](https://github.com/drosera-network/operator-monitoring-stack) It is a docker-compose stack that includes Grafana, Prometheus, Loki, and Tempo. --- # Run on Railway – Docs [Skip to content](https://dev.drosera.io/operators/railway#vocs-content) Search... [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) Menu Chevron Down Menu Railway On this page Chevron Right Follow these simple steps to deploy the Drosera Operator template on **railway.app**: Prerequisites[](https://dev.drosera.io/operators/railway#prerequisites) -------------------------------------------------------------------------- 1. **Railway Account**: Sign up or log in to [railway.app](https://railway.app/) . 2. **GitHub Account**(optional): Ensure you have a GitHub account. This allows you to use the full version of the free trial (without a github account, you will have to pay for a non-free tier in order to deploy the templates). 3. **Ethereum Private Key**: Your operator will be launched with an Ethereum account so you will need the account private key and the account will need some $ETH on the account. Currently we are only supporting Holesky testnet. You can get Holesky $ETH from a faucet of your choosing. You can get a Holesky account private key through online wallets, execution client commands, etc. Please always keep security in mind when obtaining and using private keys for any crypto application. 4. **Ethereum RPC URL**: Currently we only support Holesky RPC endpoints. Public Holesky RPC endpoints are available but the free offerings typically have strong rate limiting in place and won't function properly with the operator node. You can purchase an API key from node providers like Alchemy to get better response times and rate freedom. You can also choose to run your own Holesky RPC node and expose it to your operator. Instructions[](https://dev.drosera.io/operators/railway#instructions) ------------------------------------------------------------------------ There are two very similar railway templates for running an operator ### Deploy only the Drosera Operator[](https://dev.drosera.io/operators/railway#deploy-only-the-drosera-operator) This option allows you to run a stand-alone drosera operator. See [Run the Node](https://dev.drosera.io/operators/run-operator) for more information regarding the operator software. #### Deploy the template[](https://dev.drosera.io/operators/railway#deploy-the-template) 1. View the template: [![Deploy on Railway](https://railway.com/button.svg)](https://railway.app/template/Ndyq3N?referralCode=tVlTpv) 2. Launch the project by clicking `Deploy drosera-operator` button. 3. Configure Environment Variables * Example: Copy `DRO-ETH-RPC_URL="https://ethereum-holesky-rpc.publicnode.com" # Change this to your Holesky RPC Node URL DRO-ETH-PRIVATE_KEY="0x8406...3cdb9" # Changes this to your Holesky Ethereum Private Key` 4. Deploy the service by pressing the `Deploy` button. #### Enable Networking[](https://dev.drosera.io/operators/railway#enable-networking) In order for liveness data for this operator to be seen on the frontend, we need to add an http proxy. 1. Open the `Settings` tab of your service. 2. Navigate to the `Networking` section of the settings tab. 3. Click the `Generate Domain` button. 4. Select port `31314` port from the dropdown list (if you changed the DRO\_\_SERVER\_\_PORT variable, choose the value you set). 5. Click the `Generate Domain` button again. #### Redeploy the Operator[](https://dev.drosera.io/operators/railway#redeploy-the-operator) Now we need to redeploy the service to pick up the networking changes 1. Select the `Deployments` tab of your service. 2. In the green active deployment box, click the vertical 3 dot menu. 3. Click `Redeploy` ### Deploy a protocol-level Drosera Operator on the Drosera Testnet[](https://dev.drosera.io/operators/railway#deploy-a-protocol-level-drosera-operator-on-the-drosera-testnet) This option allows you to run an operator and delegation client for simple opt in logic. See the [Testnet Guide](https://dev.drosera.io/operators/testnet-guide) for more information about how this works. This option is for protocol-level Operators hand-selected by the Drosera Team for running public traps in our testnet. 1. View the template: [![Deploy on Railway](https://railway.com/button.svg)](https://railway.app/template/0OtXZl?referralCode=tVlTpv) 2. Launch the project by clicking `Deploy drosera-operator (testnet)` button. 3. Configure Environment Variables for both services. The environment variables with the same name should have the same values for each service. * Example: Copy `DRO-ETH-RPC_URL="https://ethereum-holesky-rpc.publicnode.com" # Change this to your Holesky RPC Node URL DRO-ETH-PRIVATE_KEY="0x8406...3cdb9" # Changes this to your Holesky Ethereum Private Key` 4. Deploy the service by pressing the `Deploy` button. #### Enable Networking[](https://dev.drosera.io/operators/railway#enable-networking-1) In order for liveness data for this operator to be seen on the frontend, we need to add an http proxy. 1. Open the `Settings` tab of your service. 2. Navigate to the `Networking` section of the settings tab. 3. Click the `Generate Domain` button. 4. Select port `31314` port from the dropdown list (if you changed the DRO\_\_SERVER\_\_PORT variable, choose the value you set). 5. Click the `Generate Domain` button again. #### Redeploy the Operator[](https://dev.drosera.io/operators/railway#redeploy-the-operator-1) Now we need to redeploy the service to pick up the networking changes 1. Select the `Deployments` tab of your service. 2. In the green active deployment box, click the vertical 3 dot menu. 3. Click `Redeploy` ### Build or Deploy Errors ??[](https://dev.drosera.io/operators/railway#build-or-deploy-errors-) 1. Check the **Deployment Logs** tab on your railway service for more details. 2. Verify that all required environment variables are configured correctly. Upgrading your Operator in Railway[](https://dev.drosera.io/operators/railway#upgrading-your-operator-in-railway) -------------------------------------------------------------------------------------------------------------------- 1. Under the `Settings` section of each service, change the `Source Image` tag to the most recent version to guarantee that the new version tag is applied. 2. Adjust the environment variable names to match any new changes to the drosera-operator and drosera-delegation-client 3. Deploy the changes. Enjoy using our template on **Railway.app**! 🚀 --- # Run with Docker – Docs [Skip to content](https://dev.drosera.io/operators/run-with-docker#vocs-content) Search... [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) Menu Chevron Down Menu Run with Docker On this page Chevron Right #### In this Guide:[](https://dev.drosera.io/operators/run-with-docker#in-this-guide) 1. Install dependencies 2. Register your operator 3. Create db directory 4. Configure and Install Docker Compose files 5. Start the drosera-operator docker compose service 6. Configure the `ufw` firewall 7. Configure Root Operator (Whitelisted Testnet Operators Only) Prerequisites[](https://dev.drosera.io/operators/run-with-docker#prerequisites) ---------------------------------------------------------------------------------- * General systems knowledge * General terminal knowledge * General cloud networking knowledge Install dependencies[](https://dev.drosera.io/operators/run-with-docker#install-dependencies) ------------------------------------------------------------------------------------------------ * Follow the [docker installation](https://docs.docker.com/engine/install/) guide for your OS. * Add current user to the docker group Copy `sudo usermod -aG docker $USER newgrp docker` Register your operator[](https://dev.drosera.io/operators/run-with-docker#register-your-operator) ---------------------------------------------------------------------------------------------------- * See [Registration documentation](https://dev.drosera.io/register) for concerns regarding what private key to use or not use. Please don't forget to update the version to the most recent version, which can be found in our [Releases Repo](https://github.com/drosera-network/releases) . Copy `export VERSION=v1.20.0 docker run ghcr.io/drosera-network/drosera-operator:${VERSION} register --eth-rpc-url https://ethereum-hoodi-rpc.publicnode.com --eth-private-key <>` Create db directory[](https://dev.drosera.io/operators/run-with-docker#create-db-directory) ---------------------------------------------------------------------------------------------- * We want a persistent location that is accessible by the service runner. * These permissions are specific to your use case, so we will make the service runnable by root and the directory accessible by root. Adjust the permissions and the systemd user as needed. Copy `sudo mkdir -p /var/lib/drosera-data sudo chown -R root:root /var/lib/drosera-data sudo chmod -R 700 /var/lib/drosera-data` Configure and Install Docker Compose files[](https://dev.drosera.io/operators/run-with-docker#configure-and-install-docker-compose-files) -------------------------------------------------------------------------------------------------------------------------------------------- * This step is probably the one that is nearly impossible to fully cover in a guide. The `drosera-operator` has many customizable features, and until you have determined your use case needs, it is impossible to make this guide fit all possible configurations. * That said, we will give a good starting configuration with reasonable defaults for the Ethereum Holesky testnet. Please refer to our [Run the Node](https://dev.drosera.io/run-operator) guide for all of the configurations, command line argument, and environment variable options and their effects on how the `drosera-operator` runs. * Before running the command below, we will explain the environment variables and what they configure. If you need an explanation of the anatomy of a `docker-compose.yml` file, [Docker's documentation](https://docs.docker.com/compose/) will get you there. * `DRO_DB_FILE_PATH`: The path to the database file to use for persistence when not in dev mode * `DRO__DROSERA_ADDRESS`: The address of the main Drosera proxy contract to interact with * `DRO__LISTEN_ADDRESS`: The network interface to bind the Operators RPC and P2P server to * `DRO__DISABLE_DNR_CONFIRMATION`: Disables the DNR confirmation. Only set this if you are running this node behind a NAT, and you are receiving a 'Failed to confirm DNR' error message. Verify the public address setting is correct and any firewall walls are opened for the configured ports before turning this setting on. * `DRO__ETH__CHAIN_ID`: The Ethereum chain id * `DRO__ETH__RPC_URL`: The node used for querying and sending transactions. You will want to set this to an Ethereum Holesky RPC that is not rate limited. Usually public nodes have significant rate limits that will cause your operator to fail RPC calls to the chain. * `DRO__ETH__BACKUP_RPC_URL`: A backup Ethereum RPC if the primary RPC node becomes unresponsive. This arg is optional. Again, this should also be a non rate-limited RPC * `DRO__ETH__PRIVATE_KEY`: The private key used to sign transactions. Please keep this secure. * `DRO__NETWORK__P2P_PORT`: The TCP port to bind the P2P server to * `DRO__NETWORK__EXTERNAL_P2P_ADDRESS`: The external address to reach the Operator node at for p2p communications. This is required for the Operator to be discoverable by other nodes. The public address can either be an IP address or a domain name. If a domain name is used, the domain must resolve to the public IP address of the Operator. It is important to note, that this is the public IPv4 address of your VPS. * `DRO__SERVER__PORT`: The TCP port to bind the rpc server to. This port is the port that must be properly allowed through the firewall in order for liveness data to be visible on the frontend. * At this point you're ready to run the command below. A good process is to copy this command into a text editor in order to replace `<>` and `<>` with the actual values. A more secure way of doing this would be to create the `.env` file in the `drosera-operator` directory and edit it with a terminal text editor like nano or vim. You can also run `history -c` in your terminal session after you're done, to clear the current terminal history so that the secrets don't show up. Please don't forget to update the version to the most recent version, which can be found in our [Releases Repo](https://github.com/drosera-network/releases) . Copy `mkdir drosera-operator cd drosera-operator tee .env > /dev/null <> VPS_PUBLIC_IP=<> DRO__NETWORK__P2P_PORT=31313 DRO__SERVER__PORT=31314 EOF tee docker-compose.yml > /dev/null <<'EOF' version: '3' services: drosera-operator: image: ghcr.io/drosera-network/drosera-operator:${VERSION} container_name: drosera-operator network_mode: host environment: - DRO__DB_FILE_PATH=/data/drosera.db - DRO__DROSERA_ADDRESS=0x91cB447BaFc6e0EA0F4Fe056F5a9b1F14bb06e5D - DRO__LISTEN_ADDRESS=0.0.0.0 - DRO__DISABLE_DNR_CONFIRMATION=true - DRO__ETH__CHAIN_ID=17000 - DRO__ETH__RPC_URL=https://ethereum-hoodi-rpc.publicnode.com - DRO__ETH__BACKUP_RPC_URL=https://1rpc.io/hoodi - DRO__ETH__PRIVATE_KEY=${ETH_PRIVATE_KEY} - DRO__NETWORK__P2P_PORT=${DRO__NETWORK__P2P_PORT}$ - DRO__NETWORK__EXTERNAL_P2P_ADDRESS=${VPS_PUBLIC_IP} - DRO__SERVER__PORT=${DRO__SERVER__PORT} volumes: - /var/lib/drosera-data:/data command: ["node"] restart: always EOF` Start the drosera-operator docker compose service[](https://dev.drosera.io/operators/run-with-docker#start-the-drosera-operator-docker-compose-service) ---------------------------------------------------------------------------------------------------------------------------------------------------------- * Start the docker compose service Copy `docker compose up -d` * Check logs: Copy `docker compose logs -f` * NOTE: the `WARN drosera_services::network::service: Failed to gossip message: InsufficientPeers` warning can be ignored. * If your `drosera-operator` is not opted into any traps, you will not see very many logs. We will cover opting into traps in another section. At this point, you can confirm that public RPC communication is properly configured on your drosera-operator with the following `curl` command. Run this command from a terminal that is not on the same network as the VPS. Copy `curl --location 'http://${YOUR_EXTERNAL_ADDRESS}:${SERVER_PORT}' \ --header 'Content-Type: application/json' \ --data '{ "jsonrpc": "2.0", "method": "drosera_healthCheck", "params": [], "id": 1 }'` * In the command `${YOUR_EXTERNAL_ADDRESS}` should be the same as what you set for the value of `DRO__NETWORK__EXTERNAL_P2P_ADDRESS` in the service file. And `${SERVER_PORT}` should be what you set for the value of `DRO__SERVER__PORT` in the service file. Securing your operator[](https://dev.drosera.io/operators/run-with-docker#securing-your-operator) ---------------------------------------------------------------------------------------------------- Since we are using docker, ufw is not a compatible software firewall. Because of the Docker networking, any incoming traffic will not hit network firewall at all. We recommend securing the operator node with a firewall external to the vm. Something like an AWS VPC firewall, or a GCP Compute Firewall would be a better way of closing off all access to this machine except for the ports needed for the operator to run and ssh access. Please see the cloud provider firewall documentation for setting up your cloud firewall. * After you have enabled the network firewall, you can again confirm RPC connectivity with your drosera-operator using the following `curl` command. Run this command from a terminal that is not on the same network as the VPS. Copy `curl --location 'http://${YOUR_EXTERNAL_ADDRESS}:${SERVER_PORT}' \ --header 'Content-Type: application/json' \ --data '{ "jsonrpc": "2.0", "method": "drosera_healthCheck", "params": [], "id": 1 }'` Configure Root Operator[](https://dev.drosera.io/operators/run-with-docker#configure-root-operator) ------------------------------------------------------------------------------------------------------ We have a closed set of whitelisted testnet operators that are running public traps. This section is for you! This command will set our Drosera team managed account as the root operator for your operator. Please update this command with your personal Hoodi RPC URL, your operator private key, and the corresponding operator address. The `root-operator-address` is already set to the address controlled by the Drosera team. Please do not change this value. Copy `docker run ghcr.io/drosera-network/drosera-operator:v1.20.0 update-root-operator --eth-rpc-url --eth-private-key --operator-addresses 0x --root-operator-address 0xd98e2ae62de96ab1d39cfcaef134692a507d38f3` Running multiple operators on one vm with one or multiple docker compose files is doable, but it requires careful attention to your port assignments and database volumes. Please ensure the following is true when building out your second operator service: * The `DRO__NETWORK__P2P_PORT` needs to be different for each operator. This is present in the docker compose service of the operator as the environment variable key `DRO__NETWORK__P2P_PORT` * The `DRO__SERVER__PORT` needs to be different for each operator. This is present in the docker compose service of the operator as the environment variable key `DRO__SERVER__PORT` * If you are running multiple delegation clients (Whitelisted Testnet Operators Only), the `DRO__NETWORK__HTTP_PORT` needs to be different for each operator. This is present in the docker compose service of the delegation-client as the environment variable key `DRO__NETWORK__HTTP_PORT` * The operators need different mount locations for their volumes. You can change the path on the left side of the colon (i.e. `/var/lib/drosera-data2`) to set a different system volume location for each operator you are running. Copy `volumes: - /var/lib/drosera-data:/data` * You will also need to create this directory on the system like we did for the first operator, using the path you set in the volume section of the docker compose file for the second operator. Copy `sudo mkdir -p /var/lib/drosera-data2 sudo chown -R root:root /var/lib/drosera-data2 sudo chmod -R 700 /var/lib/drosera-data2` --- # Run on a VPS – Docs [Skip to content](https://dev.drosera.io/operators/run-on-vps#vocs-content) Search... [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) Menu Chevron Down Menu Run on VPS On this page Chevron Right #### In this Guide:[](https://dev.drosera.io/operators/run-on-vps#in-this-guide) 1. Install dependencies 2. Install the `drosera-operator` CLI 3. Register your operator 4. Create db directory 5. Configure and Install the systemd service file 6. Enable and start the `drosera-operator` service 7. Configure the `ufw` firewall 8. Configure Root Operator (Whitelisted Testnet Operators Only) Prequisites[](https://dev.drosera.io/operators/run-on-vps#prequisites) ------------------------------------------------------------------------- * General linux systems knowledge * General terminal knowledge * General cloud networking knowledge Install dependencies[](https://dev.drosera.io/operators/run-on-vps#install-dependencies) ------------------------------------------------------------------------------------------- Copy `sudo apt-get install -y curl clang libssl-dev tar ufw` * Currently we only officially support Ubuntu 22.04 and newer. However, it is definitely possible to run drosera-operator on other hardware and OSes. However, you may have other dependencies and installation steps specific to your OS. * On non debian systems, use the package manager of your OS to install dependencies. * It is possible that your OS will have more dependencies what we have listed here. You can use your package manager to install whatever missing packages you might need if your `drosera-operator` errors because of a missing package. Install the drosera-operator CLI[](https://dev.drosera.io/operators/run-on-vps#install-the-drosera-operator-cli) ------------------------------------------------------------------------------------------------------------------- * First we need to install the `droserup` utility Copy `curl -L https://app.drosera.io/install | bash` * This script installs the `droseraup` utility into your current user's home directory under a `.drosera` directory. It also adds a line in the current user's shell profile file (e.g. `.bashrc`) that adds the `.drosera/bin` directory to the `$PATH` system variable. * Follow the terminal prompt to bring the droseraup utility into the $PATH variable. Copy `## Example terminal output: Run 'source /home/user/.bashrc' or start a new terminal session to use droseraup.` * Next we will install the `drosera` and `drosera-operator` cli Copy `droseraup` * This command installs the `latest` version of the `drosera` and `drosera-operator` cli in the home directory of the current user under a `.drosera` directory right alongside the `droseraup` utility. If you want a specific version of the cli tools, you can run the droseraup command with a version: Copy `droseraup -v v1.19.0` * Alternatively, (for automation, idempotency needs, and fewer possible failure points) you can install the pre-packaged binaries directly from the releases repository into any location you prefer (e.g. `/usr/bin/`). Make sure to set `VERSION` variable to the version you are attempting to download. Copy `mkdir -p /home/${USER}/.drosera/bin VERSION="v1.20.0" curl -LO "https://github.com/drosera-network/releases/releases/download/${VERSION}/drosera-operator-${VERSION}-x86_64-unknown-linux-gnu.tar.gz" tar -xvf "drosera-operator-${VERSION}-x86_64-unknown-linux-gnu.tar.gz" cp drosera-operator /home/${USER}/.drosera/bin/` Register your operator[](https://dev.drosera.io/operators/run-on-vps#register-your-operator) ----------------------------------------------------------------------------------------------- * See [Registration documentation](https://dev.drosera.io/register) for concerns regarding what private key to use or not use. Copy `drosera-operator register --eth-rpc-url https://ethereum-hoodi-rpc.publicnode.com --eth-private-key <>` Create db directory[](https://dev.drosera.io/operators/run-on-vps#create-db-directory) ----------------------------------------------------------------------------------------- * We want a persistent location that is accessible by the service runner. * These permissions are specific to your use case, so we will make the service runnable by root and the directory accessible by root. Adjust the permissions and the systemd user as needed. Copy `sudo mkdir -p /var/lib/drosera-data sudo chown -R root:root /var/lib/drosera-data sudo chmod -R 700 /var/lib/drosera-data` Configuring the systemd Service File[](https://dev.drosera.io/operators/run-on-vps#configuring-the-systemd-service-file) --------------------------------------------------------------------------------------------------------------------------- * This step is probably the one that is nearly impossible to fully cover in a guide. The `drosera-operator` has many customizable features, and until you have determined your use case needs, it is impossible to make this guide fit all possible configurations. * That said, we will give a good starting configuration with reasonable defaults for the Ethereum Holesky testnet. Please refer to our [Run the Node](https://dev.drosera.io/run-operator) guide for all of the configurations, command line argument, and environment variable options and their effects on how the `drosera-operator` runs. * Before running the command below, we will explain the environment variables and what they configure. If you need an explanation of the anatomy of a systemd service file, this [DigitalOcean Guide](https://www.digitalocean.com/community/tutorials/understanding-systemd-units-and-unit-files) will get you most of the way there. * `DRO_DB_FILE_PATH`: The path to the database file to use for persistence when not in dev mode * `DRO__DROSERA_ADDRESS`: The address of the main Drosera proxy contract to interact with * `DRO__LISTEN_ADDRESS`: The network interface to bind the Operators RPC and P2P server to * `DRO__ETH__CHAIN_ID`: The Ethereum chain id * `DRO__ETH__RPC_URL`: The node used for querying and sending transactions. You will want to set this to an Ethereum Holesky RPC that is not rate limited. Usually public nodes have significant rate limits that will cause your operator to fail RPC calls to the chain. * `DRO__ETH__BACKUP_RPC_URL`: A backup Ethereum RPC if the primary RPC node becomes unresponsive. This arg is optional. Again, this should also be a non rate-limited RPC * `DRO__ETH__PRIVATE_KEY`: CHANGE THIS VALUE BELOW. The private key used to sign transactions. Please keep this secure. * `DRO__NETWORK__P2P_PORT`: The TCP port to bind the P2P server to * `DRO__NETWORK__EXTERNAL_P2P_ADDRESS`: CHANGE THIS VALUE BELOW. The external address to reach the Operator node at for p2p communications. This is required for the Operator to be discoverable by other nodes. The public address can either be an IP address or a domain name. If a domain name is used, the domain must resolve to the public IP address of the Operator. It is important to note, that this is the public IPv4 address of your VPS. * `DRO__SERVER__PORT`: The TCP port to bind the rpc server to. This port is the port that must be properly allowed through the firewall in order for liveness data to be visible on the frontend. * It is also important to understand what the `ExecStart` directive is doing. Copy `ExecStart=/home/user/.drosera/bin/drosera-operator node` * This start directive is telling systemd how to start the service. In our case, we are giving it the path to the `drosera-operator` binary and the subcommand `node`. * IMPORTANT: If you installed your `drosera-operator` binary into a different location, or your current username is not `user` you need to change the path to be the path of your `drosera-operator` binary location. You can figure out this information by running `whereis drosera-operator` in your terminal. * Once you've made all of the configuration changes to your systemd service file below, you are ready to create a systemd service file in the `/etc/systemd/system/` directory with the name `drosera-operator.service` Copy `sudo tee /etc/systemd/system/drosera-operator.service > /dev/null < --eth-private-key --operator-addresses 0x --root-operator-address 0xd98e2ae62de96ab1d39cfcaef134692a507d38f3` --- # Deployments – Docs [Skip to content](https://dev.drosera.io/deployments#vocs-content) Search... [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) [![Logo](https://dev.drosera.io/img/drosera-symbol.png)](https://dev.drosera.io/) Menu Chevron Down Menu Deployments On this page Chevron Right Hoodi Testnet[](https://dev.drosera.io/deployments#hoodi-testnet) -------------------------------------------------------------------- ### Contracts[](https://dev.drosera.io/deployments#contracts) | Contract | Address | | --- | --- | | Drosera Proxy | 0x91cB447BaFc6e0EA0F4Fe056F5a9b1F14bb06e5D | | SplitsWarehouse | 0x8fb66F38cF86A3d5e8768f8F1754A24A6c661Fb8 | | SplitFactory | 0x80f1B766817D04870f115fEBbcCADF8DBF75E017 | | VestingModuleFactory | 0x23c0C62CbC87F4C4960D14dC09Ec787728FBb9d9 | | DroseraToken | 0x499b095Ed02f76E56444c242EC43A05F9c2A3ac8 | | Harvester | 0x431C17416a4e497ff01C2cFE4c1dc9e5691Ad17c | | TrapConfigBlueprint | 0xe67d60b2846a8a2207FF7908da02f85ee40E2DC8 | | TrapRewardsBlueprint | 0xf47316036E95eD0bD30074417DbB094f69646991 | ### Seed Node Relayer[](https://dev.drosera.io/deployments#seed-node-relayer) | Host | Address | | --- | --- | | Drosera Team | [https://relay.hoodi.drosera.io](https://relay.hoodi.drosera.io/) | ---