EIPs/EIPS/eip-1129.md

154 lines
7.2 KiB
Markdown

---
eip: 1129
title: Standardised DAPP announcements
author: Jan Turk (@ThunderDeliverer)
discussions-to: https://ethereum-magicians.org/t/eip-sda-standardised-dapp-announcements/508?u=thunderdeliverer
status: Draft
type: Standards Track
category: ERC
created: 2018-05-31
---
<!--You can leave these HTML comments in your merged EIP and delete the visible duplicate text guides, they will not appear and may be helpful to refer to if you edit it again. This is the suggested template for new EIPs. Note that an EIP number will be assigned by an editor. When opening a pull request to submit your EIP, please use an abbreviated title in the filename, `eip-draft_title_abbrev.md`. The title should be 44 characters or less.-->
## Simple Summary
<!--"If you can't explain it simply, you don't understand it well enough." Provide a simplified and layman-accessible explanation of the EIP.-->
Standardisation of announcements in DAPPs and services on Ethereum network. This ERC provides proposed mechanics to increase the quality of service provided by DAPP developers and service providers, by setting a framework for announcements. Be it transitioning to a new smart contract or just freezing the service for some reason.
## Abstract
<!--A short (~200 word) description of the technical issue being addressed.-->
The proposed ERC defines format on how to post announcements about the service as well as how to remove them. It also defines mechanics on posting permissions and human friendly interface.
## Motivation
<!--The motivation is critical for EIPs that want to change the Ethereum protocol. It should clearly explain why the existing protocol specification is inadequate to address the problem that the EIP solves. EIP submissions without sufficient motivation may be rejected outright.-->
Currently there are no guidelines on how to notify the users of the service status in the DAPPs. This is especially obvious in ERC20 and it's derivates. If the service is impeded by any reason it is good practice to have some sort of guidelines on how to announce that to the user. The standardisation would also provide traceability of the service's status.
## Specification
<!--The technical specification should describe the syntax and semantics of any new feature. The specification should be detailed enough to allow competing, interoperable implementations for any of the current Ethereum platforms (go-ethereum, parity, cpp-ethereum, ethereumj, ethereumjs, and [others](https://github.com/ethereum/wiki/wiki/Clients)).-->
### Structures
#### Announcer
Stores information about the announcement maker. The `allowedToPost` stores posting permissions and is used for modifiers limiting announcement posting only to authorised entities. The `name` is used for human friendly identifier of the author to be stored.
``` js
struct Announcer{
bool allowedToPost;
string name;
}
```
#### Announcement
Stores information about the individual announcement. The human friendly author identifier is stored in `author`. Ethereum address associated with the author is stored in `authorAddress`. The announcement itself is stored in `post`.
``` js
struct Announcement{
string author;
address authorAddress;
string post;
}
```
### Methods
#### the number of ammouncements
Returns the number of announcement currently active.
OPTIONAL - this method can be used to provide quicker information for the UI, but could also be retrieved from `numberOfMessages` variable.
``` js
function theNumberOfAnnouncements() public constant returns(uint256 _numberOfAnnouncements)
```
#### read posts
Returns the specified announcement as well as human friendly poster identificator (name or nickname).
``` js
function readPosts(uint256 _postNumber) public constant returns(string _author, string _post)
```
#### give posting permission
Sets posting permissions of the address `_newAnnouncer` to `_postingPrivileges` and can also be used to revoke those permissions. The `_posterName` is human friendly author identificator used in the announcement data.
``` js
function givePostingPermission(address _newAnnouncer, bool _postingPrivileges, string _posterName) public onlyOwner returns(bool success)
```
#### can post
Checks if the entity that wants to post an announcement has the posting privilieges.
``` js
modifier canPost{
require(posterData[msg.sender].allowedToPost);
_;
}
```
#### post announcement
Lets user post announcements, but only if they have their posting privileges set to `true`. The announcement is sent in `_message` variable.
``` js
function postAnnouncement(string _message) public canPost
```
#### remove announcement
Removes an announcement with `_messageNumber` announcement identifier and rearranges the mapping so there are no empty slots. The `_removalReason` is used to update users if the issue that caused the announcement is resolved or what are the next steps from the service provider / DAPP development team.
``` js
function removeAnnouncement(uint256 _messageNumber, string _removalReason) public
```
### Events
#### New announcement
MUST trigger when new announcement is created.
Every time there is a new announcement it should be advertised in this event. It holds the information about author `author` and the announcement istelf `message`.
``` js
event NewAnnouncement(string author, string message)
```
#### Removed announcement
MUST trigger when an announcement is removed.
Every time an announcement is removed it should be advertised in this event. It holds the information about author `author`, the announcement itself `message`, the reason for removal or explanation of the solution `reason` and the address of the entity that removed the announcement `remover`.
``` js
event RemovedAnnouncement(string author, string message, string reason, address remover);
```
## Rationale
<!--The rationale fleshes out the specification by describing what motivated the design and why particular design decisions were made. It should describe alternate designs that were considered and related work, e.g. how the feature is supported in other languages. The rationale may also provide evidence of consensus within the community, and should discuss important objections or concerns raised during discussion.-->
The proposed solution was designed with UX in mind . It provides mechanics that serve to present the announcements in the user friendly way. It is meant to be deployed as a Solidity smart contract on Ethereum network.
## Test Cases
<!--Test cases for an implementation are mandatory for EIPs that are affecting consensus changes. Other EIPs can choose to include links to test cases if applicable.-->
The proposed version is deployed on Ropsten testnet all of the information can be found [here](https://ropsten.etherscan.io/address/0xb04f67172b9733837e59ebaf03d277279635c8e6#readContract).
## Implementation
<!--The implementations must be completed before any EIP is given status "Final", but it need not be completed before the EIP is accepted. While there is merit to the approach of reaching consensus on the specification and rationale before writing code, the principle of "rough consensus and running code" is still useful when it comes to resolving many discussions of API details.-->
## Copyright
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).