How to monitor Ethereum transactions?

Introduction

This blog post aims to give you a brief introduction to a new beta feature called Transaction Monitors in Tangany’s Wallet as a Service API. I am going to explain how Tangany’s Transaction Monitors work and how you could configure them to suit your use cases.

There will be some configuration examples, but I’ll walk you through them step by step. If you want to start monitoring your own transactions, check out the requirements at the very bottom of this post.

Transaction Monitors explained

Upon creation, Tangany’s Transaction Monitors watch every Ethereum transaction and will notify you accordingly. This includes blocks on Mainnet and Ropsten. The monitor will search through all the new transactions and tries to find a match to the search criteria you provided on creation. When a monitor finds a match it will notify you about the matched transaction via webhooks.

Deposit Notifications and Deposit Monitoring

Get alerts whenever deposits or withdrawals are made. Monitor activities on wallets and smart contract addresses by getting automatically notified.

Benefits of monitoring transactions

Using Tangany’s monitoring infrastructure can provide numerous advantages depending on your use case. Some obvious benefits are:

Reduce operation costs

Since monitors notify you about transactions on-chain, polling transaction status becomes superfluous. Retrieving a transaction status over and over again to verify its inclusion into a block or its confirmations is consuming resources. Regardless of which hard- or software your infrastructure is built on, at some point, you will save e.g. bandwidth, processes, database operations, power, and so on.

Better safe than sorry

Supervise transactions regarding Anti Money Laundering, Anti Terrorism, or any other regulations. Tracking involved parties and receiving information about malicious transactions is an essential step towards staying compliant.

Know what’s up

Monitoring its infrastructure is crucial for every IT project. Knowing which transactions use too much gas, are more likely to fail or which wallets register a huge amount of transactions is valuable when using such insights to make improvements.

Configurations

Now we’re getting a bit more techie. Feel free to check out the requirements and information at the very bottom of this post to jump right into the action with me or review our docs about monitoring. Let’s start with probably the most basic example:

{
  "target": "transaction",
  "description": "In- and outgoing wallet txs",
  "configuration": {},
  "webhook": {
    "url": "https://your-service.tld",
  }
}

target: the target a monitor is operating on. For now, only transaction is supported
description:a maybe human-readable description of your choice
configuration: the heart of every monitor — its configuration. A Transaction Monitor will be configured to match all in- and outgoing transactions by default. We will discuss more advanced configurations later on.
webhook: a publicly available URL or IP you want your notifications to be sent to. A monitor will send a HTTP request to this endpoint which contains information about the matched transaction.

The configuration parameter has a wide range of possible filters to narrow down matched transactions. Here is a list of supported filters:

{[…]
  "configuration": {
    "direction": "in" or "out"
    "wallet": "wallet-name" or ["name0", "name1", ...]
    "from": "0x123Abc" or ["0x123Abc", ...]
    "to": "0x123Abc" or ["0x123Abc", ...]
    
    "blockNr": 0,
    "gas": 0,
    "gasPrice": "0",
    "gasUsed": 0,
    "isError": true or false,
    "nonce": 0,
    "timestamp": 1505597189,
    "value": "0.1"
  }
[…]}

Party filters like from, to and wallet can hold arrays and are evaluated using the logical operator Equals or Equals one of.
direction and isError evaluate using Equals as well.
All other configuration parameters evaluate using the logical operator Greater or Equals.

Be aware that multiple filters are combined using a logical AND. Therefore, all conditions must be met for the monitor to eventually send a notification.

Monitor parties

Transaction Monitors can be configured to notify about transactions between parties. from, to and wallet narrow down matched transactions to specified Tangany wallet names or Ethereum addresses and can even be more specific by utilizing the direction parameter. Examples:

• Monitor incoming transactions from a single Ethereum Address

{[…]
  "configuration": { "from": "0x123Abc" }
[…]}

• Monitor outgoing transactions to multiple possible Tangany wallets

{[…]
  "configuration": {
    "wallet": ["wallet-name0", "wallet-name1"]
    "direction": "out"
  }
[…]}

Monitor transaction properties

Monitoring transaction properties adapt to your use case and can be utilized in lots of different ways and combinations. Tell us about your intentions and feature requests in our 1-minute survey. Here are some examples:

• Monitor transactions that exceed a certain ETH value

{[…]
  "configuration": { "value": "0.5" }
[…]}

• Monitor failed transactions

{[…]
  "configuration": { "isError": true }
[…]}

• Surveil a wallet that is not supposed to send transactions anymore

{[…]
  "configuration": { 
    "direction": "out",
    "timestamp": 1615456830
  }
[…]}

Notifications

Transaction Monitors send notifications to an endpoint of your choice containing information about the matched transaction. This webhook can be an endpoint to your service backend, a Slack channel, or any other publicly accessible URL or IP address.

A monitor will send its notifications out once the provided transaction confirmation number is reached. Transaction confirmations indicate the number of blocks that are added to the chain subsequently. So you are in control of getting “live” notifications (confirmations: 0) or more trustworthy notifications based on higher confirmation numbers.

Following an example for a basic notification configuration:

{[…]
  "webhook": {
    "url": "https://your-service.tld",
    "method": "post"
  }
[…]}

url: the URL or IP address the monitor will send its notifications to
method: the HTTP method the monitor will utilize. post is default and can be omitted

POST webhooks

When a Transaction Monitor is configured to send notifications utilizing the HTTP method post, the incoming request from Tangany could be similar to this example:

POST https://your-service.tld HTTP/1.1
tangany-monitor: fcf66d8e-xxxx-4c5b-xxxx-5655dcfa6c69{
    "monitor": "fcf66d8e-xxxx-4c5b-xxxx-5655dcfa6c69",
    "target": "transaction",
    "description": "my monitor",
    "wallet": "my-wallet",
    "blockchain": "ethereum",
    "network": "ropsten",
    "confirmations": 6
    "configuration": {
      […] // entire configuration object
    },
    "hash": "0x69afc6e9ffa5c0ecd26451ba67081845[…]",
    "transaction": {
      […] // transaction status information
    }
}

Besides important information about the responsible monitor, the requests include data about the matched transaction. The transaction object provides all information one could get by calling Tangany’s transaction status endpoint: https://api.tangany.com/v1/eth/transaction/:hash

GET webhook

When the monitors' webhook is configured to utilize the HTTP GET method, a shortened data collection is sent by appending URL Query Parameters to the provided webhook url.

{[…]
  "webhook": {
    "url": "https://your-service.tld/some-path?key=value",
    "method": "get"
  }
[…]}

The above webhook configuration would result in monitor notification similar to the following requests:

GET https://your-service.tld/some-path?key=value
&monitor=fcf66d8e-xxxx-4c5b-xxxx-5655dcfa6c69
&target=transaction
&description=my%20monitor
&wallet=my-wallet
&blockchain=ethereum
&network=ropsten
&confirmations=6
&hash=0x69afc6e9ffa5c0ecd26451ba67081845[…] HTTP/1.1

The matched transaction, responsible for the monitor to send the notification, can be found in the hash URL Query Parameter identifiable by its transaction hash. Your predefined Query Parameters (key=value) remain untouched and will be sent along with.

Maintenance

Tangany WaaS provides the necessary functionality to keep your Transaction Monitors in a healthy state. Monitors can be retrieved in paginated lists or individually by their identifier.

Status

When retrieving an existing monitor a status will be returned that indicates its current operational state.

{[…]
  "target": "transaction",
  "description": "my-monitor",
  "configuration": {[…]},
  "webhook": {[…]},
  "status": "active",
  "invocations": {
      "failed": 3,
      "transmitted": 42
  },
[…]}

A monitors' status can be active, paused, halted and deleted, whereas deleted is only returned once — on deletion.
halted indicates an unhealthy state, likely due to infrastructural failures.
active and paused can be controlled on creating and updating requests. paused monitors will stop looking for matches and will therefore not send any notifications.

A monitors’ status request also reveals some insight about its invocations— the number of successful and failed attempts to send notifications.

Updating a monitor

A monitor can be replaced (PUT) by providing an entire valid monitor configuration. Although, the monitors id and invocation data will be preserved.

A monitor can be updated without providing an entire monitor configuration as well. If you want to stop all your monitors from sending notifications your PATCH request body should look like the following. All other properties remain untouched, only the status is altered.

{
  "status": "paused"
}

Imagine the ETH fiat value is increasing and your AML monitors are triggering too late. The value filter of some monitor configuration objects is too high. Follow the RFC JSON Patch notation to update nested properties. You could update affected monitor configurations with the following PATCH request body and no other properties will be altered.

[{ "op":"replace", "path":"/configuration/value", "value":"0.1" }]

Requirements

• Demo Account: contact Tangany’s sales & support team to obtain a free demo account to use Tangany WaaS

• Subscription Customers: contact Tangany to upgrade your existing subscription to activate a free trial

This feature is a limited beta release and may not function as promoted. Please use with caution! We recommend testing the new Transaction Monitor feature with our ready-to-use Postman Collection. Check out our last tutorial to get a quick introduction to Tangany’s Wallet as a Service API.

Constraints

• beta: the total number of Monitors is limited to 10 Monitors per customer. Contact Tangany to increase trial quotas.

• Monitors operate on public Ethereum networks only (Mainnet, Ropsten)

• Monitors always rely on an underlying wallet

• Monitor configuration properties from, to, and wallet must not exceed an array size of 10

Known issues

• Monitors may halt unexpectedly if the provided configuration yields too many matches in a short period of time

• Monitors may not increment invocations correctly if the provided configuration yields too many matches in a short period of time

• Monitors may trigger multiple times or not at all for confirmed transactions

Don’t forget to tell us what you think about Transaction Monitors in our 1-minute survey. We would love to hear about your use case and your feature requests!

For more information visit us at https://tangany.com. We’re open to any kind of feedback, so please let us know.

Take care,
Dan