From 49cfee12d4bb0bb4925d8b97fda25be100d8dd04 Mon Sep 17 00:00:00 2001 From: ligi Date: Sun, 17 Dec 2017 03:46:58 +0100 Subject: [PATCH 1/3] Introduce (warrant) Canary ERC --- EIPS/eip-canary-standard.md | 122 ++++++++++++++++++++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 EIPS/eip-canary-standard.md diff --git a/EIPS/eip-canary-standard.md b/EIPS/eip-canary-standard.md new file mode 100644 index 00000000..2ef68d9e --- /dev/null +++ b/EIPS/eip-canary-standard.md @@ -0,0 +1,122 @@ +## Preamble + + EIP: 801 + Title: ERC-801 Canary Standard + Author: ligi + Type: Standard + Category: ERC + Status: Draft + Created: 2017-12-16 + + +## Simple Summary + +A standard interface for canary contracts. + +## Abstract + +The following standard allows the implementation of canaries within contracts. +This standard provides basic functionality to check if a canary is alive, keeping the canary alive and optionally manage feeders. + +## Motivation + +The canary can e.g. be used as a [warrant canary](https://en.wikipedia.org/wiki/Warrant_canary). +A standard interface allows other applications to easily interface with canaries on Ethereum - e.g. for visualizing the state, automated alarms, applications to feed the canary or contracts (e.g. insurance) that use the state. + +## Specification + +### Methods + +#### isAlive() + +Returns if the canary was feed properly to signal e.g. that no warrant was received. + +``` js +function isAlive() constant returns (bool alive) +``` + +#### timeToLive() + +The time in seconds that can elapse between feed() calls without starving the canary dead. + +``` js +function timeToLive() constant returns (uint256 ttl) +``` + +#### feed() + +Extend the life of the canary by timeToLive() seconds. + +**NOTE**: this should trigger the event listed below + +``` js +function feed() +``` + +#### poison() + +Kills the canary instantly. E.g. in a urgent case when a warrant was received. + +``` js +function poison() +``` + +#### (optional) addFeeder(address feeder) + +Add address that is allowed to feed (and therefore also poison) the canary. + +``` js +function addFeeder(address feeder) +``` + +#### (optional) removeFeeder(address feeder) + +Remove address that is allowed to feed the canary. + +``` js +function removeFeeder(address feeder) +``` + +#### (optional) getFeederCount() + +Returns the count of addresses that are allowed to feed the canary. + +``` js +function getFeederCount() constant returns (int count) +``` + +#### (optional) getFeederByIndex(unit8 index) + +Returns the address of the feeder at the given index. + +``` js +function getFeederByIndex(unit8 index) constant returns (address feederAddress) +``` + +#### (optional) needsAllFeeders() + +When true: all feeders need to call feed() in the intervals defined by timeToLive() - analog to a multisig. +When false: all the feeders can extend the lifespan of the canary. + +This does not affect poisoning - one feeder is always enough to kill the canary. + +``` js +function needsAllFeeders() constant returns (bool needsAllFeeders) +``` + +### Events + +#### Feed + +MUST trigger when the canary got food. + +``` js +event Feed(address feeder) +``` + +## Implementation + +TODO + +## Copyright +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). From 37cfc31665b10964e3239712e1dff5b2272c8c56 Mon Sep 17 00:00:00 2001 From: ligi Date: Tue, 19 Dec 2017 11:58:50 +0100 Subject: [PATCH 2/3] Simplify - the essence of a Canary --- EIPS/eip-canary-standard.md | 83 +++++++++---------------------------- 1 file changed, 20 insertions(+), 63 deletions(-) diff --git a/EIPS/eip-canary-standard.md b/EIPS/eip-canary-standard.md index 2ef68d9e..d0a7dff5 100644 --- a/EIPS/eip-canary-standard.md +++ b/EIPS/eip-canary-standard.md @@ -2,7 +2,7 @@ EIP: 801 Title: ERC-801 Canary Standard - Author: ligi + Author: ligi Type: Standard Category: ERC Status: Draft @@ -29,89 +29,46 @@ A standard interface allows other applications to easily interface with canaries #### isAlive() -Returns if the canary was feed properly to signal e.g. that no warrant was received. +Returns if the canary was fed properly to signal e.g. that no warrant was received. ``` js function isAlive() constant returns (bool alive) ``` -#### timeToLive() +#### getBlockOfDeath() -The time in seconds that can elapse between feed() calls without starving the canary dead. +Returns the block the canary died. +Throws if the canary is alive. ``` js -function timeToLive() constant returns (uint256 ttl) +function getBlockOfDeath() constant returns (uint256 block) ``` -#### feed() +#### getType() -Extend the life of the canary by timeToLive() seconds. +Returns the type of the canary: -**NOTE**: this should trigger the event listed below +* `1` = Simple (just the pure interface as defined in this ERC) +* `2` = Single feeder (as defined in ERC-TBD) +* `3` = Single feeder with bad food (as defined in ERC-TBD) +* `4` = Multiple feeders (as defined in ERC-TBD) +* `5` = Multiple mandatory feeders (as defined in ERC-TBD) +* `6` = IOT (as defined in ERC-TBD) + +`1` might also be used for a special purpose contract that does not need a special type but still want to expose the functions and provide events as defined in this ERC. ``` js -function feed() -``` - -#### poison() - -Kills the canary instantly. E.g. in a urgent case when a warrant was received. - -``` js -function poison() -``` - -#### (optional) addFeeder(address feeder) - -Add address that is allowed to feed (and therefore also poison) the canary. - -``` js -function addFeeder(address feeder) -``` - -#### (optional) removeFeeder(address feeder) - -Remove address that is allowed to feed the canary. - -``` js -function removeFeeder(address feeder) -``` - -#### (optional) getFeederCount() - -Returns the count of addresses that are allowed to feed the canary. - -``` js -function getFeederCount() constant returns (int count) -``` - -#### (optional) getFeederByIndex(unit8 index) - -Returns the address of the feeder at the given index. - -``` js -function getFeederByIndex(unit8 index) constant returns (address feederAddress) -``` - -#### (optional) needsAllFeeders() - -When true: all feeders need to call feed() in the intervals defined by timeToLive() - analog to a multisig. -When false: all the feeders can extend the lifespan of the canary. - -This does not affect poisoning - one feeder is always enough to kill the canary. - -``` js -function needsAllFeeders() constant returns (bool needsAllFeeders) +function getType() constant returns (uint8 type) ``` ### Events -#### Feed +#### RIP -MUST trigger when the canary got food. +MUST trigger when the canary died. ``` js -event Feed(address feeder) +event RIP() ``` ## Implementation From 7c75cab96408b729a3d0e1dc861a647b63730718 Mon Sep 17 00:00:00 2001 From: ligi Date: Fri, 22 Dec 2017 11:24:31 +0100 Subject: [PATCH 3/3] Make requested changes --- EIPS/{eip-canary-standard.md => eip-801.md} | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename EIPS/{eip-canary-standard.md => eip-801.md} (90%) diff --git a/EIPS/eip-canary-standard.md b/EIPS/eip-801.md similarity index 90% rename from EIPS/eip-canary-standard.md rename to EIPS/eip-801.md index d0a7dff5..0862d691 100644 --- a/EIPS/eip-canary-standard.md +++ b/EIPS/eip-801.md @@ -55,7 +55,7 @@ Returns the type of the canary: * `5` = Multiple mandatory feeders (as defined in ERC-TBD) * `6` = IOT (as defined in ERC-TBD) -`1` might also be used for a special purpose contract that does not need a special type but still want to expose the functions and provide events as defined in this ERC. +`1` might also be used for a special purpose contract that does not need a special type but still wants to expose the functions and provide events as defined in this ERC. ``` js function getType() constant returns (uint8 type) @@ -65,7 +65,7 @@ function getType() constant returns (uint8 type) #### RIP -MUST trigger when the canary died. +MUST trigger when the contract is called the first time after the canary died. ``` js event RIP()