Run the alerts service

The alerts service warns the holder of a margin position before a weekend and before a liquidation, by email or Telegram as the holder chose. It sends no transaction, and it keeps nothing an alert does not need. You can run your own for your users, with your own sender address and bot.

Run it#

You need a registry, an RPC URL, an indexer, a public address for the links in emails, a secret of at least 32 characters, and one channel.

export ROBINHOOD_TESTNET_RPC_URL=https://rpc.testnet.chain.robinhood.com
export TAPEHOUSE_INDEXER_URL=https://indexer-production-f5dc.up.railway.app
export TAPEHOUSE_ALERTS_URL=https://alerts.example.org
export TAPEHOUSE_ALERTS_SECRET=$(openssl rand -hex 32)
export TAPEHOUSE_SMTP_URL=smtp://user:password@smtp.example.org:587
export TAPEHOUSE_ALERTS_FROM=alerts@example.org
make run-alerts CHAIN=46630

CHAIN is 4663, 46630, 42161 or 412346, and REGISTRY=<file> overrides the registry. The service listens on 127.0.0.1:8090 unless you set TAPEHOUSE_ALERTS_LISTEN.

Environment variables#

At least one channel is required: the SMTP pair, or the bot token. Setting only one of TAPEHOUSE_SMTP_URL and TAPEHOUSE_ALERTS_FROM is an error.

How a position is judged#

Each position is read through the Go SDK at one block and valued as the liquidator values it: Stock Tokens at their band's low edge, a recalled loan less its haircut, USDG at par, and WETH at 84% of Chainlink's price. A position is left unjudged while the sequencer is unsettled, while an asset it holds is halted or has an unconfirmed multiplier step, or while WETH has no price. The computed requirement must equal the engine's currentRequirement at the block's own prices, or the position is not evaluated and nothing is said of it.

For each Stock Token held, with every other asset at its band's centre, an integer bisection finds two prices:

• the weekend price, the highest centre at which the position falls short at both edges of a closed band;
• the reopening price, the highest centre at which it falls short at its low edge against the open requirement, which is where the reopening auction may enrol it.

The accounts' own open-market liquidationPrice is shown beside them. See Liquidation.

Which alerts it sends#

The service evaluates every position on the chain's clock, once for each interval.

Shorts get threshold and liquidation alerts, not a weekend price. A failed send is tried at the next two ticks and then dropped, logged by subscription ID and never by destination.

The subscription API#

POST /v1/subscriptions takes {account, channel, destination, threshold, issuedAt, signature}. The signature is an EIP-191 personal_sign by the account itself over a fixed text that names the chain, the account, the channel and issuedAt, which may be at most ten minutes old.

A Telegram subscription is confirmed with the code the response returns, opened as t.me/<bot>?start=<code> within an hour. /stop in Telegram deletes every subscription linked to that chat.

What it stores#

One table holds the subscriptions: the account, channel, destination, threshold, whether it is confirmed, the state of each position's alerts, and the SHA-256 of the unsubscribe token. A second table holds the codes and tokens awaiting confirmation, as digests, and deletes them when used or expired. An unconfirmed subscription goes with its code. No message is kept.

Channels#

Email goes over SMTP with STARTTLS, which the server must offer before the password is sent. Telegram goes over the Bot API. Both carry plain text.

Deploy on Railway#

alerts deploys from services/Dockerfile with SERVICE=alerts. Set TAPEHOUSE_ALERTS_LISTEN=[::]:8090, TAPEHOUSE_ALERTS_DB=/data/alerts.db, TAPEHOUSE_INDEXER_URL, TAPEHOUSE_ALERTS_URL and TAPEHOUSE_ALERTS_SECRET, with the channel's variables. It keeps its subscriptions in SQLite, so it needs a volume at /data, RAILWAY_RUN_UID=0 because Railway mounts volumes as root, and exactly one replica. It serves only /v1/... routes and has no health check path. To check it after a deployment, add its URL to SERVICE_URLS in scripts/verify-deployment.sh to confirm that it answers below 500.

Security#

The RPC URLs, the SMTP password, the bot token and the secret never appear in a log. Treat TAPEHOUSE_ALERTS_SECRET as a key: changing it invalidates every unsubscribe link already sent.

Next#

• Run the indexer
• Liquidation
• Portfolio margin