From 2a5f278a0a14750ed1216083378f4def808dd873 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Piotr=20Kosi=C5=84ski?= Date: Mon, 30 Jul 2018 10:52:22 +0200 Subject: [PATCH 1/4] Chronologic / Piper standard --- standards/chronologic-piper.md | 124 +++++++++++++++++++++++++++++++++ 1 file changed, 124 insertions(+) create mode 100644 standards/chronologic-piper.md diff --git a/standards/chronologic-piper.md b/standards/chronologic-piper.md new file mode 100644 index 0000000..b6559a5 --- /dev/null +++ b/standards/chronologic-piper.md @@ -0,0 +1,124 @@ +# Specification + +## Summary +A standardized interface for interacting with subscriptions. + +## Abstract +This standard defines a contract interface for interacting with subscription data. The scope of this proposal is end-user / wallet interactions. Creation of the subscriptions is out-of-scope of this ERC. + +## Our Thoughts +From the subscriber's side: + +* I want strong guarantees on when I can cancel my subscription. +* I will normally want payments to happen automatically without any action on my part. +* In some cases it might be valuable to require an approval process. +* For dynamically priced subscriptions I want to be able to set limits (require authorization if subscription is more than X). + + +From the providers's side: + +* I need the ability to charge a fixed fee per subscription time unit (netflix, pandora, etc). +* I need the ability to charge a dynamic fee per subscription time unit (aws, twilio, etc). +* I need to be able to create reasonably accurate forecasts for upcoming subscriptions: Programatic checks that subscription accounts have available balance and that subscription is active. + +## Motivation +Standard that covers all usecases of subscription based model with minimal interface suitable for wallets. + +### Interface + +#### cancel + +Immediately cancels the subscription. Implementations should ensure that any unpaid subscription payments are paid to the provider as part of cancellation to ensure providers are able to let subscriptions fees fill up for arbitrary lengths of time, allowing them to reduce overhead from transaction costs. + +```SOLIDITY + +/** @dev Cancels the subscription + * @return true if cancellation succedded +*/ + +function cancel() + public + returns (bool success); +``` + +#### isFunded + +Checkes if there is enough funds available for provider to collect + +```SOLIDITY + +/** @dev Cancels the subscription + * @return true if there is enough funds allowed to the contract to pay for subscription +*/ + +function isFunded() + public + returns (bool funded); +``` + +#### availableFunds + +Returns the amount of ETH or tokens available for the provider to collect + + +```SOLIDITY + +/** @dev The amount of ETH or tokens available for the provider + * @return available funds +*/ + +function availableFunds() + public + returns (uint256 funds); +``` + +#### metadata + +Returns the off-chain location for metadata. +By *metadata* we define a self-described data not required by on-chain contract logic and thus possible to be kept off-chain. An example provided [here](#metadata-example) + +```SOLIDITY + +/** @dev Serialized bytes of subscription data + * @return available funds +*/ + +function metdata() + public + returns (bytes metadata); +``` + + + +### Implementation + +A minimal implementation would require the following fields. + +* `address token`: defines the token contract which payments are paid from. +* `address provider`: the address of the provider +* `uint256 time_unit`: the number of seconds per time unit. +* `uint256 tokens_per_time_unit`: the number of tokens that can be paid towards the subscription per time_unit. +* `uint256 last_payment_at`: the timestamp when the last payment was made. + +In order to allow triggering payments by external parties the contract can follow EIP #1228. + +The `execute` method would call `token.transfer(provider, (now - last_payment_at) * tokens_per_time_unit / time_unit)`. + +### Metadata example + +Basic information about the subscription like: +* name = "Monthly subscription" +* description = "Any other extra description to be visible from wallet" +* key = "value" + +Which can be JSON serialized as + +```Json +{"name":"Monthly subscription","description":"Any other extra description to be visible from wallet","key":"value"} +``` + +Things to consider: +* limit for amout of keys and values + +### Conclusion +This is our suggestions for the beginning of a standardization on interaction with subscription data on the Ethereum blockchain. We are open to suggestions, concerns, or rejections. Let's collaborate and build a better ecosystem. \ No newline at end of file From 52de7a6baa162f07a015791811e4f05ed995e83b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Piotr=20Kosi=C5=84ski?= Date: Mon, 30 Jul 2018 11:00:58 +0200 Subject: [PATCH 2/4] Update chronologic-piper.md --- standards/chronologic-piper.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/standards/chronologic-piper.md b/standards/chronologic-piper.md index b6559a5..7cb5e89 100644 --- a/standards/chronologic-piper.md +++ b/standards/chronologic-piper.md @@ -83,7 +83,7 @@ By *metadata* we define a self-described data not required by on-chain contract * @return available funds */ -function metdata() +function metadata() public returns (bytes metadata); ``` @@ -118,7 +118,7 @@ Which can be JSON serialized as ``` Things to consider: -* limit for amout of keys and values +* limit for amount of keys and values ### Conclusion -This is our suggestions for the beginning of a standardization on interaction with subscription data on the Ethereum blockchain. We are open to suggestions, concerns, or rejections. Let's collaborate and build a better ecosystem. \ No newline at end of file +This is our suggestions for the beginning of a standardization on interaction with subscription data on the Ethereum blockchain. We are open to suggestions, concerns, or rejections. Let's collaborate and build a better ecosystem. From 242e33a284c9dd3b163707ace95c71e71480939c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Piotr=20Kosi=C5=84ski?= Date: Mon, 30 Jul 2018 12:36:46 +0200 Subject: [PATCH 3/4] Minor typo fixes. --- standards/chronologic-piper.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/standards/chronologic-piper.md b/standards/chronologic-piper.md index 7cb5e89..932261c 100644 --- a/standards/chronologic-piper.md +++ b/standards/chronologic-piper.md @@ -43,7 +43,7 @@ function cancel() #### isFunded -Checkes if there is enough funds available for provider to collect +Checkes if there is enough funds available for the provider to collect ```SOLIDITY @@ -106,7 +106,7 @@ The `execute` method would call `token.transfer(provider, (now - last_payment_at ### Metadata example -Basic information about the subscription like: +Basic information about the subscription: * name = "Monthly subscription" * description = "Any other extra description to be visible from wallet" * key = "value" @@ -118,7 +118,7 @@ Which can be JSON serialized as ``` Things to consider: -* limit for amount of keys and values +* limit the amount of keys and values ### Conclusion This is our suggestions for the beginning of a standardization on interaction with subscription data on the Ethereum blockchain. We are open to suggestions, concerns, or rejections. Let's collaborate and build a better ecosystem. From 5e42e39566aff2266f13bdaefe7d23a1ebb25c70 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Piotr=20Kosi=C5=84ski?= Date: Thu, 9 Aug 2018 09:26:46 +0200 Subject: [PATCH 4/4] Update chronologic-piper.md --- standards/chronologic-piper.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/standards/chronologic-piper.md b/standards/chronologic-piper.md index 932261c..2f7721f 100644 --- a/standards/chronologic-piper.md +++ b/standards/chronologic-piper.md @@ -72,20 +72,20 @@ function availableFunds() returns (uint256 funds); ``` -#### metadata +#### metadataURI -Returns the off-chain location for metadata. +Returns URI (RFC 3986) for subscription metadata By *metadata* we define a self-described data not required by on-chain contract logic and thus possible to be kept off-chain. An example provided [here](#metadata-example) ```SOLIDITY -/** @dev Serialized bytes of subscription data - * @return available funds +/** @dev URI string to subscription metadata + * @return URI to metadata */ -function metadata() +function metadataURI() public - returns (bytes metadata); + returns (string metadataURI); ```