Bond Notifications

The notification system monitors the state of your validator bond and alerts you when something important changes.

The notification system monitors the state of your validator bond and alerts you when something important changes.

How Notifications Work

The processing pipeline works as follows:

1. State monitoring - The system periodically checks the state of all bonds participating in the SAM Auction (bond balance, auction status, eligibility, etc.).

2. Change detection - When a relevant change is detected for your bond (e.g., your bond becomes underfunded, you exit the auction), an event is generated.

3. Notification delivery - The event is evaluated, prioritized, and delivered to you via your subscribed channels (Telegram, Email, or the CLI notifications view).

You only receive notifications when something changes. The system does not repeatedly alert you about a persistent condition. For ongoing issues (e.g., underfunding), re-alerts are sent at most once per 24 hours and only if the condition changed significantly.

Notification Types

• Bond underfunded - Your bond's SOL balance is insufficient to cover SAM Auction costs for the delegated stake. The system tracks how many epochs your current balance can sustain. You'll receive a critical alert when coverage drops below 2 epochs, and a warning when it drops below 10 epochs. Only deficits >= 0.5 SOL trigger a notification.

• Auction exited / entered - Your validator left or joined the SAM Auction. Exiting is critical. Act quickly to avoid losing delegated stake.

• Cap constraint changed - The binding constraint limiting your delegated stake changed. Only the BOND cap type (your bond size is the limiting factor) triggers a notification; other cap types (e.g., country) are system-managed and suppressed.

• Bond removed - Bond is no longer visible in on-chain data. This is a critical alert. This may indicate accidental bond closure. You will lose all delegated stake if not resolved.

• Bond balance changed - SOL balance on your bond account changed.

• SAM eligibility changed - Validator SAM eligibility toggled (e.g., due to delinquency). Ineligibility means Marinade won't delegate to you even if your bid is competitive.

• Announcements - Broadcast messages from Marinade to all validators.

We are currently in beta. Thresholds, priority levels, and notification frequency may change during testing.

---

Subscribing to Notifications

Requirements

• The validator-bonds CLI - install it via npm: npm install -g @marinade.finance/validator-bonds-cli

• Your bond authority keypair or validator identity keypair (file-based keypair or Ledger hardware wallet)

Subscribe via Telegram

validator-bonds subscribe <BOND_OR_VOTE_ACCOUNT> \
  --type telegram \
  --address @YourTelegramHandle \
  --authority /path/to/authority-keypair.json

The CLI signs an off-chain message with your authority keypair to prove bond ownership. Your browser then opens a Telegram deep link. Press Start in the bot to activate. Notifications are not delivered until you confirm in Telegram. If the browser does not open automatically, copy the link from the CLI output manually.

The Telegram activation is required every time you subscribe or re-subscribe, even for the same bond. Always go through the CLI first.

Subscribe via Email

validator-bonds subscribe <BOND_OR_VOTE_ACCOUNT> \
  --type email \
  --address [email protected] \
  --authority /path/to/authority-keypair.json

Unlike Telegram, email subscriptions are active immediately. No additional confirmation step is needed.

Subscription Scope

A subscription currently covers all notification types for the given bond. Granular subscription modes (e.g., subscribing only to critical alerts or specific event types) are not available at this time and may be added in the future.

Viewing Your Subscriptions

To see your active subscriptions for a bond:

validator-bonds subscriptions <BOND_OR_VOTE_ACCOUNT> \
  --authority /path/to/authority-keypair.json

Use -f json or -f yaml for machine-readable output.

Unsubscribing

Unsubscribe a specific channel address:

validator-bonds unsubscribe <BOND_OR_VOTE_ACCOUNT> \
  --type telegram \
  --address @YourTelegramHandle \
  --authority /path/to/authority-keypair.json

Unsubscribe all subscriptions of a given type (omit --address):

validator-bonds unsubscribe <BOND_OR_VOTE_ACCOUNT> \
  --type telegram \
  --authority /path/to/authority-keypair.json

Unsubscribing requires signing with the bond authority or validator identity keypair, the same as subscribing.

Viewing Notifications

validator-bonds show-notifications <BOND_OR_VOTE_ACCOUNT>

Notifications have a relevance window (typically 2–5 days depending on the event type). Older notifications will no longer appear in this view.

To view broadcast announcements from Marinade:

validator-bonds show-notifications

Quick Reference

Action	Command
Subscribe (Telegram)	validator-bonds subscribe <BOND> --type telegram --address @handle --authority keypair.json
Subscribe (Email)	validator-bonds subscribe <BOND> --type email --address [email protected] --authority keypair.json
List subscriptions	validator-bonds subscriptions <BOND> --authority keypair.json
Unsubscribe specific	validator-bonds unsubscribe <BOND> --type telegram --address @handle --authority keypair.json
Unsubscribe all of type	validator-bonds unsubscribe <BOND> --type telegram --authority keypair.json
View notifications	validator-bonds show-notifications <BOND>
View announcements	validator-bonds show-notifications

<BOND> can be either a bond account address or a vote account address.

Ledger Hardware Wallet Support

All subscribe and unsubscribe commands support Ledger hardware wallets. Pass your Ledger as the --authority option and the CLI will prompt you to confirm the off-chain message signing on the device.

---

Feedback

This notification system is under active development. If you have feedback on notification content, frequency, missing events, or the subscription experience, please reach out to us on Discord.