decentraland/ethalarm

⏰ Get notifications whenever an Ethereum smart contract triggers an event.

ethalarm

Get notified of events triggered by Ethereum contracts.

Running

Run the server using:

npm install
npm start

Now, go to http://localhost:3000 and the frontend should be displayed to you.

TODO

• Add some security to fetch
• Optimize scanner so it doesn't read the whole database each time
• Add tests

API

POST /alarms

Creates a new alarm, based on data posted through a JSON. To activate email alerts, an email should be dispatched to the user with a unique hash that should be confirmed (see the POST /emails/:email/confirmation endpoint).

The request content should follow this schema:

{
  "id": "https://github.com/decentraland/eventlog#POST-Request",
  "$schema": "http://json-schema.org/draft-06/schema#",
  "description": "Schema for a POST request to /alarm",
  "type": "object",
  "required": [ "address", "abi", "events", "confirmations" ],
  "properties": {
    "address": {
      "description": "The contract's address",
      "type": "string"
    },
    "abi": {
      "description": "The contract's ABI",
      "type": "string"
    },
    "events": {
      "description": "List of event names to watch for",
      "type": "array",
      "items": { "type": "string" }
    },
    "hook": {
      "description": "The URL to query when a new event is generated",
      "type": "string"
    },
    "email": {
      "description": "Email to send a notification",
      "type": "string"
    },
    "confirmations": {
      "description": "Amount of confirmations to wait before notifying",
      "type": "number"
    }
  }
}

Example request body:

{
  "address": "0xcca95e580bbbd04851ebfb85f77fd46c9b91f11c",
  "events": ["LockedBalance"],
  "hook": "https://decentraland.org/",
  "confirmations": 6,
  "abi": "[{\"constant\":false,\"inputs\":[{\"name\":\"target\",\"type\":\"address\"}],\"name\":\"setTargetContract\",\"outputs\":[],\"payable\":false,\"type\":\"function\"},{\"constant\":true,\"inputs\":[],\"name\":\"totalLocked\",\"outputs\":[{\"name\":\"\",\"type\":\"uint256\"}],\"payable\":false,\"type\":\"function\"},{\"constant\":false,\"inputs\":[{\"name\":\"_acceptingDeposits\",\"type\":\"bool\"}],\"name\":\"changeContractState\",\"outputs\":[],\"payable\":false,\"type\":\"function\"},{\"constant\":false,\"inputs\":[{\"name\":\"_from\",\"type\":\"address\"},{\"name\":\"mana\",\"type\":\"uint256\"}],\"name\":\"lockMana\",\"outputs\":[],\"payable\":false,\"type\":\"function\"},{\"constant\":true,\"inputs\":[],\"name\":\"manaToken\",\"outputs\":[{\"name\":\"\",\"type\":\"address\"}],\"payable\":false,\"type\":\"function\"},{\"constant\":true,\"inputs\":[],\"name\":\"owner\",\"outputs\":[{\"name\":\"\",\"type\":\"address\"}],\"payable\":false,\"type\":\"function\"},{\"constant\":true,\"inputs\":[],\"name\":\"landClaim\",\"outputs\":[{\"name\":\"\",\"type\":\"address\"}],\"payable\":false,\"type\":\"function\"},{\"constant\":true,\"inputs\":[{\"name\":\"\",\"type\":\"address\"}],\"name\":\"lockedBalance\",\"outputs\":[{\"name\":\"\",\"type\":\"uint256\"}],\"payable\":false,\"type\":\"function\"},{\"constant\":true,\"inputs\":[],\"name\":\"acceptingDeposits\",\"outputs\":[{\"name\":\"\",\"type\":\"bool\"}],\"payable\":false,\"type\":\"function\"},{\"constant\":false,\"inputs\":[{\"name\":\"newOwner\",\"type\":\"address\"}],\"name\":\"transferOwnership\",\"outputs\":[],\"payable\":false,\"type\":\"function\"},{\"inputs\":[{\"name\":\"_token\",\"type\":\"address\"}],\"payable\":false,\"type\":\"constructor\"},{\"payable\":true,\"type\":\"fallback\"},{\"anonymous\":false,\"inputs\":[{\"indexed\":false,\"name\":\"user\",\"type\":\"address\"},{\"indexed\":false,\"name\":\"mana\",\"type\":\"uint256\"}],\"name\":\"LockedBalance\",\"type\":\"event\"},{\"anonymous\":false,\"inputs\":[{\"indexed\":false,\"name\":\"target\",\"type\":\"address\"}],\"name\":\"LandClaimContractSet\",\"type\":\"event\"},{\"anonymous\":false,\"inputs\":[{\"indexed\":false,\"name\":\"user\",\"type\":\"address\"},{\"indexed\":false,\"name\":\"value\",\"type\":\"uint256\"},{\"indexed\":false,\"name\":\"data\",\"type\":\"bytes\"}],\"name\":\"LandClaimExecuted\",\"type\":\"event\"},{\"anonymous\":false,\"inputs\":[{\"indexed\":false,\"name\":\"_acceptingDeposits\",\"type\":\"bool\"}"
}

The response body for this method follows a simple schema:

{
  "id": "https://github.com/decentraland/ethalarm#POST-Response",
  "$schema": "http://json-schema.org/draft-06/schema#",
  "description": "Schema for a POST response of /alarm",
  "type": "object",
  "properties": {
    "ok": {
      "description": "Whether the request was successfull or not",
      "type": "bool"
    },
    "error": {
      "description": "If there was an error, a human-readable error explaining it",
      "type": "string"
    },
    "result": {
      "type": "object",
      "properties": {
        "id": {
          "description": "An ID to identify the recently created alarm",
          "type": "string"
        }
      }
    }
  }
}

GET /alarms/:id

This method should return the data stored in the database for this alarm. It could also return information about triggered alerts for those alarms.

DELETE /alarms/:id

Stop watching the alarm referenced.

POST /confirmations/:hash

Confirmation to start sending emails for the given hash.

ethalarm's Issues

web3.eth.subscribe not working

Hello,

This tool looks awesome, tried to make it work for me but couldn't get the alerts.

See web3/web3.js#1093

Any help appreciated :)

Thanks

UI error on 'HowNotify' step if 'email' field is not used

Hi, cool project!

I'm trying to add a webhook but the 'HowNotify' step errors if 'email' field is left blank - it's calling ".trim()" on null.

https://github.com/decentraland/ethalarm/blob/master/src/webapp/containers/steps/howNotify.js#L26

Bounty: Make EthAlarm Usable

1. Refactor and clean up the logic [1.5 ETH]

Right now the approach to detect events is very inefficient - when a new block comes the past few blocks are fetched and checks are made that notifications have not been sent. I've also observed some race conditions.
Possible solution: Walk through up to the nearest common ancestor of the blockchain (usually just 1 block, but you have to be sensitive to block reorgs).

REQUIREMENTS:

• Add tests
• Refactor and stick to prettier as configured here
• Ensure preventable race conditions are not present.

2. Document and simplify project setup [0.5 ETH]

In order to provide users with an 'out-of-the-box' experience and devs with a stress-free start to using this repo, setting up the project should be streamlined and easy to understand.

REQUIREMENTS:

• Cleanup and simplify code as you find necessary to streamline project setup
• Create an easy-to-follow guide to configure a clean setup of this repo
• Ensure docker compose and other setup components are working well

3. Pay feature [1 ETH]

The first x notifications should be free, but after that limit has been reached, the recipient must pay the operator a configurable amount.

REQUIREMENTS:

• All implemented code must be covered by tests
• The number of emails and price should be configurable

4a. Dashboard feature, Part 1 [0.75 ETH]

Users should get all relevant information about their alarms in one place.

REQUIREMENTS:

• All implemented code must be covered by tests
• Add a Dashboard to see a listing of all users, emails, current alarms.
• Use an authentication mechanism that requires a web3-compatible browser.

4b. Dashboard feature, Part 2 [0.75 ETH]

ADMIN users should have additional abilities when using the dashboard.

PRE-REQUISITES:

• Task 4a (Dashboard Feature I) must be completed before this task

REQUIREMENTS:

• All implemented code must be covered by tests
• Admins should be able to:
  • Whitelist users from hitting any limit
  • Blacklist email domains
  • See IP logs of users
  • Ban users

If you have questions about the tasks, please feel free to contact Dax on our chat or visit the development channel

My alarms didn't trigger?

Heya team,

again, thanks so much for this tool! Love it.

I signed up to send me notifications of events on my contract but I haven't received any notices yet. Even though they should have arrived. Is there any chance I could get some help in debugging why this happened? Here's my alarm:

https://ethalarm.com/info/cbb055ff-ca49-46be-ad7c-2c1c4ad3d3e3

There's been Payment, Withdrawal & TokensClaimed events since I signed up for the notices. Let me know if there's anything I can help with here.

Kovan testnet

Hey guys,

It is really cool tool. Highly appreciated!

Do you have any plan to support Kovan network too?

Thanks,

-Samandar