communities.md 15.3 KB
Newer Older
roadscape's avatar
roadscape committed
1
# Hive Communities Design
roadscape's avatar
roadscape committed
2
3

## Introduction
roadscape's avatar
roadscape committed
4
5

> We believe that high-quality content and communities of content producers and their
6
7
audiences are the primary driver of growth of the hive.blog site, and in turn the wider
adoption of the platform and HIVE. To this end, we wish to enable many users to build
roadscape's avatar
roadscape committed
8
9
10
11
12
13
14
15
16
17
18
communities in parallel around curating specific types of content valuable to their audiences.

> To enable this, we intend to augment our current tag-based organizational structure for posts
with a new system called “communities”, a special group into which others can post articles.
Two types of communities will exist: communities into which anyone in the world can post
(where community founders (or their delegated moderators) can decide, post-hoc, which
posts to hide from view) or communities in which only community founders’ (or their
delegated authors’) posts will appear.

> This system of moderation will function identically to the aforementioned comment
moderation system, with all content (including hidden or moderated content) published
19
permanently in the blockchain to prevent censorship. The hive.blog web site will respect
roadscape's avatar
roadscape committed
20
21
22
23
24
25
26
27
28
29
the display preferences of the specific community maintainers (within their own community
namespace only) while simultaneously propagating every participant’s voice throughout the
blockchain to the entire world (regardless of moderator opinions).

> We believe this unique approach finally solves one of the largest problems currently
presented to social media services: the dichotomy between maintaining a high Signal-to-Noise
Ratio (SNR) for a quality content experience free of spam and low-value comments,
whilst simultaneously preventing any type of censorship.

> It is our hope and design goal for our services (all of which are published with full source code
roadscape's avatar
roadscape committed
30
31
32
33
34
> for easy deployment by anyone) to be replicated by others, displaying content according to
> the wishes and whims of each individual website operator, giving readers ultimate choice
> over the set of moderation opinions they wish to heed. 
>
> *[source](https://steem.io/2017roadmap.pdf)*
roadscape's avatar
roadscape committed
35

36
Today, most Hive frontends rely on the global tags system for organization. In this sense Hive has many "communities" already but they are entirely informal; there is no ownership and no ability to formally organize. Tag usage standards are not possible to enforce, and users have different goals as to what they want to see and what sort of communities they want each tag to embody. 
roadscape's avatar
roadscape committed
37

38
Hive communities add a governance layer which allows users to organize around a set of values, and gives them the power to do so effectively. It introduces a new system of moderation which is not dependent on users' hive power. By making it easier to organize, this system can be far more effective at connecting creators and curators. Curators will be attracted to communities which are well-organized: focused, high-quality, low-noise. Making it easier to find the highest quality content will make it easier to reward high quality content.
roadscape's avatar
roadscape committed
39

roadscape's avatar
roadscape committed
40
Many people want to see long-form, original content while many others just want to share links and snippets. The goal of the community feature is to empower users to create tighter groups and focus on what's important to them. Use cases for communities may include:
roadscape's avatar
roadscape committed
41

roadscape's avatar
roadscape committed
42
 - microblogging & curated journals
roadscape's avatar
roadscape committed
43
 - local meetups
roadscape's avatar
roadscape committed
44
 - link sharing
roadscape's avatar
roadscape committed
45
46
47
48
49
50
 - world news
 - curation guilds (cross-posting undervalued posts, overvalued posts, plagiarism, etc)
 - original photography
 - funny youtube videos
 - etc

roadscape's avatar
roadscape committed
51
52
53
54
## Overview

#### Community Types

roadscape's avatar
roadscape committed
55
All communities and posts are viewable and readable by all, and there is a governance mechanism which can affect visibility and prioritization of content for the purpose of decreasing noise and increasing positive interactions (however a community wishes to define it) and discourse. By default, communities are open for all to post and comment ("topics"). However, an organization may create a restricted community ("journal") for official updates: only members of the organization would be able to post updates, but anyone can comment. Alternatively, a professional group or local community ("council") may choose to limit all posting and commenting to approved members (perhaps those they verify independently).
roadscape's avatar
roadscape committed
56

roadscape's avatar
roadscape committed
57
58
59
1. **Topic**: anyone can post or comment
2. **Journal**: guests can comment but not post. only members can post.
3. **Council**: only members can post or comment
roadscape's avatar
roadscape committed
60

roadscape's avatar
roadscape committed
61
#### User Roles Overview
roadscape's avatar
roadscape committed
62
63

1. **Owner**: can assign admins. 
roadscape's avatar
roadscape committed
64
2. **Admin**: can edit community properties and assign mods.
roadscape's avatar
roadscape committed
65
66
67
3. **Mod**: can mute posts/users, add/remove members, pin posts, set user titles.
4. **Member**: in restricted (journal/council) communities, an approved member.
5. **Guest**: can post/comment in topics and comment in journals.
roadscape's avatar
roadscape committed
68
69
70

#### User Actions

roadscape's avatar
roadscape committed
71
**Owner** has the ability to:
roadscape's avatar
roadscape committed
72
73
74
75
76
77
78

- **set admins**: assign or revoke admin priviledges

**Admins** have the ability to:

- **set moderators**: grant or revoke mod priviledges
- **set payout split**: control reward sharing destinations/percentages
roadscape's avatar
roadscape committed
79
- **set display settings**: control the look and feel of community home pages
roadscape's avatar
roadscape committed
80
81
82

**Moderators** have the ability to:

roadscape's avatar
roadscape committed
83
84
- **set user roles:** member, guest, muted
- **set user titles**: ability to add a label for specific users, designating role or status
roadscape's avatar
roadscape committed
85
86
87
- **mute posts**: prevents the post from being shown in the UI (until unmuted)
- **pin posts**: ability for specific posts to always show at the top of the community feed

roadscape's avatar
roadscape committed
88
**Members** have the ability to:
roadscape's avatar
roadscape committed
89

roadscape's avatar
roadscape committed
90
91
92
- **in an topic**: N/A (no special abilities)
- **in a journal: post** (where guests can only comment)
- **in a council: post and comment** (where guests cannot)
roadscape's avatar
roadscape committed
93
94
95

**Guests** have the ability to:

roadscape's avatar
roadscape committed
96
97
- **post in a topic**: as long as they are not muted
- **comment in a topic or journal**: as long as they are not muted
roadscape's avatar
roadscape committed
98
99
- **flag a post**: adds an item and a note to the community's moderation queue for review
- **follow a community**: to customize their feed with communities they care about
roadscape's avatar
roadscape committed
100

roadscape's avatar
roadscape committed
101
## Registration
roadscape's avatar
roadscape committed
102

roadscape's avatar
roadscape committed
103
104
105
##### NCI: Numerical Community Identifier

Communities are registered by creating an on-chain account which conforms to `/^hive-[1-3]\d{4,6}$/`, with the first digit signifying the *type*. Type mappings are outlined in a later section. Thus the valid range is  `hive-10000` to `hive-3999999` for a total of 1M possible communities per type. This ensures the core protocol has stable ids for linking data without introducing a naming system.
roadscape's avatar
roadscape committed
106

roadscape's avatar
roadscape committed
107
##### Custom URLs
roadscape's avatar
roadscape committed
108

roadscape's avatar
roadscape committed
109
Name registration, particularly in decentralized systems, is far from trivial. The ideal properties for registering community URLs include:
roadscape's avatar
roadscape committed
110

roadscape's avatar
roadscape committed
111
112
113
114
1. ability to claim a custom URL based on a subjective capacity to lead that community
2. ability to reassign a URL which has ceased activity (due to lost key or inactivity)
3. ability to reassign a URL due to trademark issues
4. decentralization: no central entity is controlling registration or collecting payments
roadscape's avatar
roadscape committed
115

roadscape's avatar
roadscape committed
116
Name reassignments result unpredictable and/or complex behavior, which is why internal identifiers are not human-readable. This approach does not preclude anyone from developing a standardized naming system. Such a system may be objective and automated or subjective and voting driven. For subjective approaches, starting with just a numerical id is particularly useful as it allows a community to demonstrate its prowess before making a case to claim a specific human-readable identifier.
roadscape's avatar
roadscape committed
117

roadscape's avatar
roadscape committed
118
## Considerations
roadscape's avatar
roadscape committed
119

roadscape's avatar
roadscape committed
120
121
122
- Operations such as role grants and mutes are not retroactive.
  - This is to allow for consistent state among services which can also be replayed independently, as well as for simplicity of implementation. If it is needed to batch-mute old posts, this can be still be accomplished by issuing batch `mutePost` operations.
  - Example: If a user is muted, the state of their previous posts is not changed. If the user attempts to post in a community during this period (e.g. from a UI which does not properly enforce roles), their posts will be marked "invalid" since they did not have the correct priviledge at the time. Likewise, if they are unmuted, any of these "invalid" posts remain so.
roadscape's avatar
roadscape committed
123
124
  - Example: payout split changes cannot be retroactive, otherwise previously valid posts may be considered invalid.
- A post's `community` cannot be changed after the post is created. This avoids a host of edge cases.
roadscape's avatar
roadscape committed
125
126
127
- A community can only have one account named as the owner.
- Each user in a community is assigned, at most, 1 role (admin, mod, member, guest, muted).
- Anybody could be promoted to member, mod, or admin of any community, but they will be shown as inactive unless they are subscribed to the community.
roadscape's avatar
roadscape committed
128
129
130
131
132
133

## Community Metadata

##### Editable by Admins - Core Settings

Core settings which will influence community logic and validation rules.
roadscape's avatar
roadscape committed
134

roadscape's avatar
roadscape committed
135
 - `reward_share`: (v1.5) dictionary mapping `account` to `percent`
roadscape's avatar
roadscape committed
136
137
138
    - specifies required minimum beneficiary amount per post for it to be considered valid
    - can be blank or contain up to 8 entries

roadscape's avatar
roadscape committed
139
##### Editable by Admins - Community Properties
roadscape's avatar
roadscape committed
140

roadscape's avatar
roadscape committed
141
Can be stored as a JSON dictionary.
roadscape's avatar
roadscape committed
142

143
 - `title`: the display name of this community (32 chars)
roadscape's avatar
roadscape committed
144
 - `about`: short blurb about this community (120 chars)
roadscape's avatar
roadscape committed
145
146
 - `lang`: primary language. `en`, `es`, `ru`, etc (https://en.wikipedia.org/wiki/ISO_639-3 ?)
 - `is_nsfw`: `true` if this community is 18+. UI to automatically tag all posts/comments `nsfw`
roadscape's avatar
roadscape committed
147
148
 - `description`: a blob of markdown to describe purpose, enumerate rules, etc. (5000 chars)
 - `flag_text`: custom text for reporting content
roadscape's avatar
roadscape committed
149
 - `settings': json dict; recognized keys:
150
151
152
   - `avatar_url` - same format as account avatars; usually rendered as a circle
   - `cover_url` - same format as account covers; used as header background image
   - `default_view` = `list | blog | grid` - default post display
roadscape's avatar
roadscape committed
153
154
   - `bg_color`: background color - hex-encoded RGB value (e.g. `#EEDDCC`)
   - `bg_color2`: background color - hex-encoded RGB value (if provided, creates a gradient)
roadscape's avatar
roadscape committed
155

roadscape's avatar
roadscape committed
156
Extra settings (v1.5)
roadscape's avatar
roadscape committed
157
158
159

 - `comment_display`: default comment display method (e.g. `votes`, `trending`, `age`, `forum`) 
 - `feed_display`: specify graphical layout in communities
roadscape's avatar
roadscape committed
160

roadscape's avatar
roadscape committed
161
162
163
164
165
166
167
168
169
170


## Registration

Register an onchain account name which conforms to `/hive-[1-3]\d{4,6}$/`. This is the owner account. From this account, submit a `setRole` command to set the first admin.

- Topics: the leading digit must be `1`
- Journals: the leading digit must be `2`
- Councils: the leading digit must be `3` 

roadscape's avatar
roadscape committed
171
172
## Operations

roadscape's avatar
roadscape committed
173
Communities are not part of blockchain consensus, so all operations take the form of `custom_json` operations which are to be monitored and validated by separate services to build and maintain state.
roadscape's avatar
roadscape committed
174
175
176
177
178
179
180

The standard format for `custom_json` ops:

```
{
  required_auths: [],
  required_posting_auths: [<account>],
roadscape's avatar
roadscape committed
181
  id: "community",
roadscape's avatar
roadscape committed
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
  json: [
    <action>, 
    {
      community: <community>, 
      <params*>
    }
  ]
}
```

 - `<account>` is the account submitting the `custom_json` operation.  
 - `<action>` is a string which names a valid action, outlined below.
 - `<community>` required parameter for all ops and names a valid community.  
 - `<params*>` is any number of other parameters for the action being performed

roadscape's avatar
roadscape committed
197
### Setting Roles
roadscape's avatar
roadscape committed
198
199

```
roadscape's avatar
roadscape committed
200
201
202
["setRole", {
    "community": <community>,
    "account": <account>,
Smittyvb's avatar
Smittyvb committed
203
    "role": admin|mod|member|none|muted,
roadscape's avatar
roadscape committed
204
    "notes": <comment>
roadscape's avatar
roadscape committed
205
206
207
}]
```

roadscape's avatar
roadscape committed
208
*Owner* can set any role.
roadscape's avatar
roadscape committed
209

roadscape's avatar
roadscape committed
210
*Admins* can set the role of any account to any level below `admin`, except for other *Admins*.
roadscape's avatar
roadscape committed
211

roadscape's avatar
roadscape committed
212
*Mods* can set the role of any account to any level below `mod`, except for other *Mods*.
roadscape's avatar
roadscape committed
213

roadscape's avatar
roadscape committed
214
215
### Admin Operations

roadscape's avatar
roadscape committed
216
In addition to editing user roles (e.g. appointing mods), admins can define the reward share and control display settings.
roadscape's avatar
roadscape committed
217

roadscape's avatar
roadscape committed
218
#### Update display settings
roadscape's avatar
roadscape committed
219
220

```
roadscape's avatar
roadscape committed
221
["updateProps", {
roadscape's avatar
roadscape committed
222
  "community": <community>, 
roadscape's avatar
roadscape committed
223
  "props": { <key:value>, ... }
roadscape's avatar
roadscape committed
224
225
226
}]
```

roadscape's avatar
roadscape committed
227
Valid keys are `title`, `about`, `lang`, `is_nsfw`, `description`, `flag_text`, `settings`.
roadscape's avatar
roadscape committed
228

roadscape's avatar
roadscape committed
229
#### Set reward share (v1.5)
roadscape's avatar
roadscape committed
230
231

```
roadscape's avatar
roadscape committed
232
["setRewardShare", {
roadscape's avatar
roadscape committed
233
  "community": <community>, 
roadscape's avatar
roadscape committed
234
  "reward_share": { <account1>: <percent1>, ... }
roadscape's avatar
roadscape committed
235
236
237
}]
```

roadscape's avatar
roadscape committed
238
### Moderator Operations
roadscape's avatar
roadscape committed
239

roadscape's avatar
roadscape committed
240
In addition to editing user roles (e.g., approving a member or muting a user), mods have the ability to set user titles, mute posts, and pin posts.
roadscape's avatar
roadscape committed
241
242
243
244
245
246
247
248
249
250
251

#### Set user title

```
["setUserTitle", {
  "community": <community>,
  "account": <account>,
  "title": <title>
}]
```

roadscape's avatar
roadscape committed
252
#### Mute/unmute a post
roadscape's avatar
roadscape committed
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273

Can be a topic or a comment.

```
["mutePost", {
  "community": <community>,
  "account": <account>,
  "permlink": <permlink>
  "notes": <comment>
}]
```

```
["unmutePost", {
  "community": <community>,
  "account": <account>,
  "permlink": <permlink>,
  "notes": <comment>
}]
```

roadscape's avatar
roadscape committed
274
Any posts muted for spam should contain simply the string `spam` in the `notes` field. This standardized label will help train automated spam detection.
roadscape's avatar
roadscape committed
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289

#### Pin/unpin a post

Stickies a post to the top of the community homepage. If multiple posts are stickied, the newest ones are shown first.

```
["pinPost", {
  "community": <community>,
  "account": <account>,
  "permlink": <permlink>
}]
```


```
roadscape's avatar
roadscape committed
290
["unpinPost", {
roadscape's avatar
roadscape committed
291
292
293
294
295
296
  "community": <community>,
  "account": <account>,
  "permlink": <permlink>
}]
```

roadscape's avatar
roadscape committed
297
### Guest Operations
roadscape's avatar
roadscape committed
298

roadscape's avatar
roadscape committed
299
#### Un/subscribe to a community
roadscape's avatar
roadscape committed
300

roadscape's avatar
roadscape committed
301
302
303
304
305
306
307
Allows a user to signify which communities they want shown on their personal trending feed and to be shown in their navigation menu.

```
["subscribe", {
  "community": <community>
}]
```
roadscape's avatar
roadscape committed
308

roadscape's avatar
roadscape committed
309
310
311
312
313
```
["unsubscribe", {
  "community": <community>
}]
```
roadscape's avatar
roadscape committed
314
315
316
317
318
319
320
321

#### Flag a post

Places a post in the review queue. It's up to the community to define what constitutes flagging.

```
["flagPost", {
  "community": <community>,
roadscape's avatar
roadscape committed
322
  "account": <account>,
roadscape's avatar
roadscape committed
323
324
325
326
327
  "permlink": <permlink>,
  "comment": <comment>
}]
```

roadscape's avatar
roadscape committed
328
#### Posting in a community
roadscape's avatar
roadscape committed
329
330
331
332
333

To mark a post as belonging to a community, set the `community` key in `json_metadata`. Do not use an `@` prefix.

```
{
roadscape's avatar
roadscape committed
334
    "community": "hive-192921",
335
    "app": "hiveblog/0.1",
roadscape's avatar
roadscape committed
336
    "format": "html",
337
    "tags": ["hive"],
roadscape's avatar
roadscape committed
338
339
340
341
    [...]
}
```

roadscape's avatar
roadscape committed
342
If a post is edited to name a different community, this change will be ignored.   If a post is posted "into" a community which does not exist, or one that the user does not have permission to post into, the json will be interpreted as if the "community" key does not exist, and the post will be posted onto the user's own blog.
roadscape's avatar
roadscape committed
343

roadscape's avatar
roadscape committed
344
345
346
347




roadscape's avatar
roadscape committed
348
349
---

roadscape's avatar
roadscape committed
350
351
352


## Appendix A. Interface Considerations
roadscape's avatar
roadscape committed
353

roadscape's avatar
roadscape committed
354
355


roadscape's avatar
roadscape committed
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
 - community home
    - apply custom display
    - list posts by trending or created
    - un/subscribe button
    - new post button
 - communities index
    - trending/popular communities
    - keyword search
    - must show follow status
 - mod tools
   - user titles
   - pin/unpin post
   - mute/unmute user
   - mute/unmute post
- mod settings
  - list and edit approved and muted users
  - moderation queue
  - moderation log
- admin settings
  - edit community settings
  - edit mods list
- owner settings
    - community creation
    - assign mods
roadscape's avatar
roadscape committed
380

roadscape's avatar
roadscape committed
381
382
383
384
385


## Appendix B. Example Database Schema

Not complete -- for reference only.
roadscape's avatar
roadscape committed
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400

```
accounts
  id
  name

communities
  account_id
  type [0,1,2]
  name
  about
  description
  language
  is_nsfw
  settings
roadscape's avatar
roadscape committed
401
402
  is_valid
  
roadscape's avatar
roadscape committed
403
404
405
406
407
408
409
410
411

members
  community_id
  account_id
  is_admin
  is_mod
  is_approved
  is_muted
  title
roadscape's avatar
roadscape committed
412
413
  promoted_at
  demoted_at
roadscape's avatar
roadscape committed
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442

posts
  id
  parent_id
  author
  permlink
  community
  created_at
  is_pinned
  is_muted

posts_cache
  post_id
  title
  preview
  payout_at
  rshares

flags
  account_id
  post_id
  notes

modlog
  account_id
  community_id
  action
  params
```
roadscape's avatar
roadscape committed
443
444
445
446
447
448
449



## Appendix C. Reference

1. Stratos subapp: Communities

Smittyvb's avatar
Smittyvb committed
450
   https://github.com/stratos-steem/stratos/wiki/Subapp:-Communities