Webhook icon
Schedule icon
If icon
Fail icon
Request icon
Queries icon
Query icon
SlackIncomingWebhook icon
Pause icon
LoopUntil icon

Watch the Smart Contracts You Depend On for Upgrades and Ownership Changes

Alert on smart contract upgrades and ownership changes, approve them with an audit trail, or pause your protocol.

Categories
BusinessInfrastructure

Most tokens, oracles and bridges are upgradeable: whoever controls the proxy can replace the code behind an address that thousands of integrations trust. A planned upgrade can still change behavior you rely on, and a hijacked admin or owner key can do it silently. Several large DeFi losses began with exactly that kind of change, and no integrator noticed in time. This blueprint keeps an approved baseline for every contract your product depends on and makes each change a reviewed, recorded decision.

How it works

  1. contract_event (Webhook) runs a check as soon as your on-chain alerting sees an Upgraded, AdminChanged, BeaconUpgraded or OwnershipTransferred event. periodic_check (Schedule) also catches changes that emit no event.
  2. read_contracts reads, in one JSON-RPC batch, for every contract:
    • its code;
    • the EIP-1967 implementation, admin and beacon slots, plus the older OpenZeppelin slots that proxies such as USDC's use;
    • owner().
  3. resolve (Postgres) decodes the batch and classifies each contract: EIP-1967 proxy, beacon proxy, legacy OpenZeppelin proxy, or plain contract. Proxies that keep their admin in an immutable (Aave V3 does) show no admin; their implementation is still watched. read_implementations then fetches each implementation's code and the implementation each beacon points to.
  4. analyze (Postgres) compares the current state with the approved baseline in contract_watch:
    • the first sighting becomes the baseline;
    • a change is reported once, with a line per field: implementation: 0x… → 0x…;
    • a change of owner, admin or beacon, or an implementation without code, is CRITICAL; a new implementation is an UPGRADE;
    • a contract that returns to its approved state is reported as such.
  5. propose asks on-call, through a Pause of up to 4 hours:
    • Approve as new baseline, with a note;
    • Pause the protocol;
    • Not yet: the change stays unapproved and is proposed again after remind_minutes.
  6. approve_changes approves exactly the state that was shown. pause_protocol sends pause() to your contract from the guardian through your signer, waits for the receipt (LoopUntil), and reads paused() to confirm.

Every baseline, change, restore and approval is written to contract_watch_log with the execution id and note.

Error handling

  • Approvals never cover more than was shown. Each proposal carries a fingerprint of the state on-call saw. If the contract changed again while the approval waited, it is "NOT approved: it changed again after the proposal", and the new change is reported separately. Names in only_contracts that were not proposed are listed as not part of the proposal.
  • Monitoring continues during a decision. The flow has no concurrency limit, so other runs keep checking while one waits for an answer. The conditional UPDATE in analyze ensures that two concurrent runs never both report or propose the same change.
  • A pause is verified, not assumed. If the signer refuses or the call would revert (for example, the guardian is not allowed), the run fails with the node's message and says the protocol is NOT paused. If the transaction is mined but paused() is still false, it fails the same way.
  • Configuration mistakes fail loudly:
    • malformed entries are rejected before any RPC call;
    • an address with no contract on this chain (a typo, or the wrong network) fails instead of becoming an empty baseline;
    • RPC errors other than a missing owner() fail the run.
  • Every failure is reported. RPC calls retry with backoff, and the errors alert names the task, the cause and a link to the execution.

What this blueprint teaches about Kestra

  • Two-stage JSON-RPC batching: a first templated batch built from flow variables, and a second batch that Postgres generates from the first one's results.
  • Change detection with a baseline table, where a conditional UPDATE ... RETURNING makes alerts exactly-once even with overlapping executions.
  • A Pause whose answer is bound to what was shown, so a late approval cannot approve something newer.
  • A human-approved circuit breaker: an on-chain action, a LoopUntil for the receipt, and a read-back that confirms the effect.

Prerequisites

  • An RPC endpoint for the chain (any provider; no special APIs).
  • A Postgres database and a Slack incoming webhook.
  • Optional, for the pause answer: your contract with pause() and paused(), a guardian address allowed to call it, and a signer for that guardian (Web3Signer, a KMS relayer, a Safe module relayer) on a private network. Kestra never holds keys.

Secrets

  • EVM_RPC_URL: JSON-RPC endpoint.
  • EVM_SIGNER_URL: signer accepting eth_sendTransaction for the guardian (only for the pause answer).
  • POSTGRES_URL, POSTGRES_USER, POSTGRES_PASSWORD: state and audit log.
  • SLACK_WEBHOOK_URL: Slack incoming webhook.

Inputs

  • contracts (ARRAY): Label=0xaddress entries. The defaults watch USDC and the Chainlink ETH/USD feed on Ethereum mainnet.
  • remind_minutes (INT, default 60): how often an unapproved change is proposed again.
  • pause_target, guardian (STRING, optional): your pausable contract and its guardian.
  • explorer_url, kestra_url (STRING): links in Slack.

Outputs

  • contracts (JSON): each contract with its kind, current state, whether it is approved, and what changed.

Quick start

  1. Add the secrets, then run the flow with the default inputs against a mainnet RPC: Slack lists USDC as a legacy OpenZeppelin proxy with its implementation and admin, and the Chainlink feed with its owner.
  2. Replace contracts with the tokens, oracles, bridges and proxies your product depends on, one network per flow (copy the flow for each chain).
  3. Point your on-chain alerting at the contract_event webhook and change its key.
  4. When an upgrade is announced, approve it with a link to the announcement as the note; the audit log keeps it.
  5. To use the circuit breaker, set pause_target and guardian, and give the signer the guardian key.

Plugins used

See How

New to Kestra?

Use blueprints to kickstart your first workflows.