ERC-801 Warrant canary signaling standard (Canary Standard)

Stagnant · Other · created 2017-12-16

Defines a standard interface for checking whether a 'canary' contract that periodically refreshes a signal indicating it has not received a legal request, such as a warrant, is still alive, for querying when it died, and for distinguishing its type.

Why it is needed

A warrant canary is a mechanism by which an operator implicitly signals that they have not received a secret subpoena or warrant, through periodic signal updates. When implementing this as a contract, without a standard interface, each service ends up with its own way of checking liveness, querying the time of death, and distinguishing canary types. This makes it hard for wallets or monitoring apps to read and visualize the status of multiple canaries at once or trigger automatic alerts, and anything built on top, such as an app that feeds the canary or an insurance contract that acts based on canary status, would need separate integration code for each canary. With standardized query functions and events, these applications can read a canary's life/death status, time of death, and type in a consistent way and integrate easily.

What to implement

In depth

The isAlive function

The source defines isAlive() as returning a boolean indicating whether the canary has been properly fed. This is used, for example, to signal that no warrant has been received. Exactly how feeding works and how often it must be refreshed is not specified by this standard, and is left to be defined in separate documents for each subtype distinguished by getType().

The getBlockOfDeath function

Returns the block number at which the canary died as a uint256. The source specifies that calling this function while the canary is still alive must throw. In other words, this function only returns a valid value for a dead canary.

The getType function and canary types

getType() returns a uint8 value distinguishing the canary's type. The source defines 1 as Simple, implementing only this ERC's pure interface, 2 as Single feeder, 3 as a single-feeder type with a bad food concept, 4 as Multiple feeders, 5 as Multiple mandatory feeders, and 6 as IOT type. However, the detailed specifications for types 2 through 6 were marked as 'ERC-TBD' at the time the source was written, and were only meant to be defined in separate documents rather than being included in the source itself.

The RIP event

The RIP event must be fired the first time a call occurs after the canary has died. This event serves as a trigger that lets external applications detect the canary's death and automate alerts or follow-up actions.

Use case and purpose

The source cites the warrant canary as the use case for this standard. A warrant canary is a mechanism by which an operator implicitly signals that they have not received a secret subpoena or warrant, through periodic signal updates. It explains that a standard interface enables various applications, such as status visualization, automated alarms, feeding apps, and insurance contracts that use canary status, to integrate easily with canaries.

Standard status

This proposal was written in December 2017 and is currently in Stagnant status. The detailed specifications for types 2 through 6 mentioned in getType() ('ERC-TBD') were never completed as separate documents, and the Implementation section remains marked TODO, leaving the proposal stalled.

Original ERC · ← ERCs