Skip to content

Latest commit

 

History

History
1701 lines (765 loc) · 42.6 KB

index.md

File metadata and controls

1701 lines (765 loc) · 42.6 KB

Protocol Documentation

Table of Contents

Top

proto/App.proto

AppAction

Field Type Label Description
app_id string required ID of application
metadata bytes optional Metadata
raw_action bytes optional Raw metadata of wrapped action
signature bytes optional Signature over app commitment

AppActionMetadata

Field Type Label Description
video_id string optional YouTube video ID

AppAction.ActionType

Name Number Description
CREATE_VIDEO 0
CREATE_CHANNEL 1

AppAction.CreatorType

Name Number Description
CHANNEL 0
MEMBER 1
CURATOR_GROUP 2

Top

proto/Bounty.proto

BountyMetadata

Field Type Label Description
title string optional Bounty title
description string optional Bounty description
discussionThread uint64 optional Id of the forum thread used to discuss the bounty
banner_image_uri string optional Image uri of the bounty's banner

BountyWorkData

Field Type Label Description
title string optional Title of the work
description string optional Description which contains the work itself as a URL, a BLOB, or just text

Top

proto/Channel.proto

ChannelMetadata

Field Type Label Description
title string optional Channel Title
description string optional Channel Description
is_public bool optional Wether to display channel to the public
language string optional ISO_639-1 Language Code
cover_photo uint32 optional index into external assets array
avatar_photo uint32 optional index into external assets array

Top

proto/ChannelPayouts.proto

ChannelPayoutsMetadata

Field Type Label Description
header ChannelPayoutsMetadata.Header required Payload header
body ChannelPayoutsMetadata.Body required Payload body

ChannelPayoutsMetadata.Body

Channel payout full body structure, it will not be downloaded by clients in full

Field Type Label Description
channel_payouts ChannelPayoutsMetadata.Body.ChannelPayoutProof repeated List of channel payouts

ChannelPayoutsMetadata.Body.ChannelPayoutProof

Field Type Label Description
channel_id uint32 required
cumulative_reward_earned string required Since protobuf does not support 128 bit unsigned inetgers so string representation is being used here, after message decoding the string would be converted to BN to pervent precision loss
merkle_branch ChannelPayoutsMetadata.Body.ChannelPayoutProof.ProofElement repeated
reason string required reward rationale for channel;

ChannelPayoutsMetadata.Body.ChannelPayoutProof.ProofElement

Field Type Label Description
hash string required
side ChannelPayoutsMetadata.Body.ChannelPayoutProof.Side required

ChannelPayoutsMetadata.Header

Fields in the payload header are encoded in fixed length 32/64 bits instead of varint encoding (uint64/32). This allows first calculating, and then setting the byte offset of each ChannelPayoutProof accurately, e.g. byte_offset = size(Header) + position_where_record_for_channel_exists_in_Body If varint encoding is used for header fields, then calculating the byte offset of ChannelPayoutProof w.r.t the start of the payload would be improbable since the header size won't be known.

Field Type Label Description
payload_length_in_bytes fixed64 required Length in bytes of entire payload
header_length_in_bytes fixed64 required Length in bytes of payload header
number_of_channels fixed32 required Number of channels
channel_payout_byte_offsets ChannelPayoutsMetadata.Header.ChannelPayoutByteOffset repeated List of byte offsets for all channels

ChannelPayoutsMetadata.Header.ChannelPayoutByteOffset

Field Type Label Description
channel_id fixed32 required Channel id
byte_offset fixed64 required Byte offset from start of payload where payout record for given channel Id exists

ChannelPayoutsMetadata.Body.ChannelPayoutProof.Side

Name Number Description
Left 0
Right 1

Top

proto/Council.proto

CouncilCandidacyNoteMetadata

Field Type Label Description
header string optional Candidacy header text
bullet_points string repeated Candidate program in form of bullet points
banner_image_uri string optional Image uri of candidate's banner
description string optional Candidacy description (md-formatted)

Top

proto/Forum.proto

ForumPostMetadata

Field Type Label Description
text string optional Post text content (md-formatted)
repliesTo uint32 optional Id of the post that given post replies to (if any)

ForumThreadMetadata

Field Type Label Description
title string optional Thread title
tags string repeated Tags accociated with the thread. Any update overrides all current tags. Only the first {MAX_TAGS_PER_FORUM_THREAD} (const exposed via @joystream/metadata-protobuf/consts) tags are taken into account. In order to unset current tags, [''] (array with empty string) must be provided as value.

Top

proto/Membership.proto

MembershipMetadata

Field Type Label Description
name string optional Member's real name
avatar_object uint32 optional Member's avatar - index into external assets array
avatar_uri string optional Url to member's avatar
about string optional Member's md-formatted about text
externalResources MembershipMetadata.ExternalResource repeated

MembershipMetadata.ExternalResource

Field Type Label Description
type MembershipMetadata.ExternalResource.ResourceType optional
value string optional

MembershipMetadata.ExternalResource.ResourceType

Name Number Description
EMAIL 0
HYPERLINK 1
TWITTER 2
TELEGRAM 3
DISCORD 4
FACEBOOK 5
YOUTUBE 6
MATRIX 7
IRC 8
WECHAT 9
WHATSAPP 10
LINKEDIN 11
GITHUB 12

Top

proto/Metaprotocol.proto

AppMetadata

Field Type Label Description
website_url string optional Url where user can read more about the project or company for this app
use_uri string optional Url to the app
small_icon string optional
medium_icon string optional
big_icon string optional
one_liner string optional Tagline for the app
description string optional
terms_of_service string optional
auth_key string optional
platforms string repeated List of platforms on which the app will be available, e.g. [mobile, web, native]
category string optional E.g messaging, adult

BanOrUnbanMemberFromChannel

Field Type Label Description
member_id uint64 required ID of the member that channel owner wants to ban from participating on any video.
option BanOrUnbanMemberFromChannel.Option required Selected option to ban or unban member from the channel

ChannelModeratorRemarked

Field Type Label Description
moderate_comment ModerateComment optional

ChannelOwnerRemarked

Field Type Label Description
pin_or_unpin_comment PinOrUnpinComment optional
ban_or_unban_member_from_channel BanOrUnbanMemberFromChannel optional
video_reactions_preference VideoReactionsPreference optional
moderate_comment ModerateComment optional

CreateApp

Field Type Label Description
name string required
app_metadata AppMetadata optional

CreateComment

create comment

Field Type Label Description
video_id uint64 required ID of the video
parent_comment_id string optional ID of comment member wants to reply (empty if new comment is parent comment)
body string required Comment text

CreateVideoCategory

Field Type Label Description
name string required
description string optional
parent_category_id string optional

DeleteComment

delete comment by author

Field Type Label Description
comment_id string required ID of the comment which will be deleted

EditComment

edit comment by author

Field Type Label Description
comment_id string required ID of the comment whose text is being edited
new_body string required New comment body

MakeChannelPayment

Field Type Label Description
rationale string optional Reason why payment is being made
video_id uint64 optional Other possible contexts, e.g. playlist etc.

MemberRemarked

Field Type Label Description
react_video ReactVideo optional
react_comment ReactComment optional
create_comment CreateComment optional
edit_comment EditComment optional
delete_comment DeleteComment optional
create_video_category CreateVideoCategory optional
create_app CreateApp optional
update_app UpdateApp optional
make_channel_payment MakeChannelPayment optional DeleteApp delete_app = 9;

ModerateComment

delete comment by moderator or channel owner;

Field Type Label Description
comment_id string required ID of comment that will be deleted by moderator
rationale string required why moderator wants to delete this comment

PinOrUnpinComment

pin comment on a video by channel owner

Field Type Label Description
video_id uint64 required ID of the video
comment_id string required ID of the comment which will be pinned
option PinOrUnpinComment.Option required Selected option to pin or unpin comment from channel

ReactComment

reacting, unreacting to a comment

Field Type Label Description
comment_id string required ID of the comment to react
reaction_id uint32 required ID of the selected reaction

ReactVideo

reacting, unreacting, and changing reaction to video

Field Type Label Description
video_id uint64 required ID of the video to react
reaction ReactVideo.Reaction required Selected reaction

UpdateApp

Field Type Label Description
app_id string required
app_metadata AppMetadata optional

VideoReactionsPreference

Enable or disable reactions on a single video

Field Type Label Description
video_id uint64 required ID of the video
option VideoReactionsPreference.Option required Selected option to enable or disable comment section

BanOrUnbanMemberFromChannel.Option

Name Number Description
BAN 0 Ban member (nothing happens if member is already banned)
UNBAN 1 Unban member (nothing happens if member is already unbanned)

PinOrUnpinComment.Option

Name Number Description
PIN 0 Pin comment on video (nothing happens if comment is already pinned)
UNPIN 1 Unpin comment from video (nothing happens if comment is already unpinned)

ReactVideo.Reaction

The enum must be wrapped inside "message", otherwide it breaks protobufjs Reacting again with the same message option will cancel the previous reaction

Name Number Description
LIKE 0
UNLIKE 1

VideoReactionsPreference.Option

Name Number Description
ENABLE 0 Enable reactions (nothing happens if they are already enabled)
DISABLE 1 Disable reactions (nothing happens if they are already disabled)

Top

proto/Person.proto

PersonMetadata

Field Type Label Description
first_name string optional
middle_name string optional
last_name string optional
about string optional
cover_photo uint32 optional index into external assets array
avatar_photo uint32 optional index into external assets array

Top

proto/ProposalsDiscussion.proto

ProposalsDiscussionPostMetadata

Field Type Label Description
text string optional Post text content (md-formatted)
repliesTo uint32 optional Id of the post that given post replies to (if any)

Top

proto/Series.proto

SeasonMetadata

Field Type Label Description
title string optional
description string optional
cover_photo uint32 optional index into external assets array
persons uint64 repeated Person(s) referenced by PersonId involved in this Season

SeriesMetadata

Field Type Label Description
title string optional
description string optional
cover_photo uint32 optional index into external assets array
persons uint64 repeated Person(s) referenced by PersonId involved in this Series

Top

proto/Storage.proto

DistributionBucketFamilyMetadata

Field Type Label Description
region string optional ID / name of the region covered by the distribution family (ie. us-east-1). Should be unique.
description string optional Additional, more specific description of the region
areas GeographicalArea repeated Standarized geographical areas covered by the family (providing [{}] will unset the current value)
latency_test_targets string repeated List of targets (hosts/ips) best suited latency measurements for this family

DistributionBucketOperatorMetadata

Field Type Label Description
endpoint string optional Root distribution node endpoint (ie. https://example.com/distribution)
location NodeLocationMetadata optional Information about node's phisical location (providing {} will unset current value)
extra string optional Additional information about the node / node operator

GeoCoordiantes

Field Type Label Description
latitude float optional
longitude float optional

GeographicalArea

Field Type Label Description
continent GeographicalArea.Continent optional
country_code string optional ISO 3166-1 alpha-2 country code
subdivision_code string optional ISO 3166-2 subdivision code

NodeLocationMetadata

Field Type Label Description
country_code string optional ISO 3166-1 alpha-2 country code (2 letters)
city string optional City name
coordinates GeoCoordiantes optional Geographic coordinates (providing {} will unset current value)

StorageBucketOperatorMetadata

Field Type Label Description
endpoint string optional Root storage node endpoint (ie. https://example.com/storage)
location NodeLocationMetadata optional Information about node's phisical location (providing {} will unset current value)
extra string optional Additional information about the node / node operator

GeographicalArea.Continent

Name Number Description
AF 1
NA 2
OC 3
AN 4
AS 5
EU 6
SA 7

Top

proto/Token.proto

Benefit

Field Type Label Description
title string optional
description string optional
emoji string optional
display_order uint32 optional

CreatorTokenIssuerRemarked

Field Type Label Description
update_token_metadata UpdateTokenMetadata optional

SaleMetadata

Field Type Label Description
terms_and_conditions string optional

TokenMetadata

Field Type Label Description
name string optional Title
symbol string optional Symbol
description string optional token description
avatar_object uint32 optional avatar for token - index into external assets array
avatar_uri string optional Url to member's avatar
benefits Benefit repeated benefits for tokne
whitelist_application_note string optional note for applicant
whitelist_application_apply_link string optional link to application process
trailer_video_id uint64 optional runtime id for video trailer

UpdateTokenMetadata

Field Type Label Description
new_metadata TokenMetadata optional

Top

proto/Video.proto

ContentMetadata

Field Type Label Description
video_metadata VideoMetadata optional ... Other possible metadata standards, e.g. PlaylistMetadata

License

License types defined by Joystream

Field Type Label Description
code uint32 optional License code defined by Joystream. reference
attribution string optional Text for licenses that require an attribution
custom_text string optional Text for custom license type

MediaType

Codec, Container, MIME media-type information

Field Type Label Description
codec_name string optional Codec corresponding to name field from FFmpeg
container string optional Video container format, eg. 'MP4', 'WebM', 'Ogg' ref
mime_media_type string optional MIME Media Type, eg. 'video/mp4' ref

PublishedBeforeJoystream

Publication status before joystream

Field Type Label Description
is_published bool optional Was video published before joystream platform
date string optional Date of publication: 'YYYY-MM-DD' ISO-8601

SubtitleMetadata

Field Type Label Description
type string required
new_asset uint32 optional index into external assets array
language string required ISO_639-1 Language Code
mimeType string required

VideoMetadata

Field Type Label Description
title string optional Video Title
description string optional Video Description
video uint32 optional index into external assets array
thumbnail_photo uint32 optional index into external assets array
duration uint32 optional Lengths of video in seconds
media_pixel_height uint32 optional Resolution of the video (Height)
media_pixel_width uint32 optional Resolution of the video (Width)
media_type MediaType optional Encoding and Container format used
language string optional ISO_639-1 Language Code
license License optional License type for the media
published_before_joystream PublishedBeforeJoystream optional Date of publication
has_marketing bool optional Does video have marketing or advertising in the stream
is_public bool optional Should video be publicy visible yet
is_explicit bool optional Does Video have explicit language or scenes
persons uint64 repeated Person(s) referenced by PersonId involved in this video
category string optional Video Category Id
subtitles SubtitleMetadata repeated Video subtitles
enable_comments bool optional Enable/Disable the comment section
clear_subtitles bool optional Remove all subtitles; since protobuf doesn't distinguish b/w empty array and null field, simply removing all subtitles by overriding list with an empty array wont work
is_short bool optional Is video a short format, vertical video (e.g. Youtube Shorts, TikTok, Instagram Reels)

Top

proto/WorkingGroups.proto

AddUpcomingOpening

Field Type Label Description
metadata UpcomingOpeningMetadata optional Upcoming opening metadata

ApplicationMetadata

Field Type Label Description
answers string repeated List of answers to opening application form questions

ModeratePost

Field Type Label Description
post_id uint64 required
rationale string required

OpeningMetadata

Field Type Label Description
short_description string optional Short description of the opening
description string optional Full description of the opening
hiring_limit uint32 optional Expected number of hired applicants
expected_ending_timestamp uint32 optional Expected time when the opening will close (Unix timestamp)
application_details string optional Md-formatted text explaining the application process
application_form_questions OpeningMetadata.ApplicationFormQuestion repeated List of questions that should be answered during application
title string optional

OpeningMetadata.ApplicationFormQuestion

Field Type Label Description
question string optional The question itself (ie. "What is your name?"")
type OpeningMetadata.ApplicationFormQuestion.InputType optional Suggested type of the UI answer input

RemarkMetadataAction

Field Type Label Description
moderate_post ModeratePost optional
verify_validator VerifyValidator optional

RemoveUpcomingOpening

Field Type Label Description
id string optional Upcoming opening query-node id

SetGroupMetadata

Field Type Label Description
new_metadata WorkingGroupMetadata optional New working group metadata to set (can be a partial update)

UpcomingOpeningMetadata

Field Type Label Description
expected_start uint32 optional Expected opening start (timestamp)
reward_per_block uint64 optional Expected reward per block
min_application_stake uint64 optional Expected min. application stake
metadata OpeningMetadata optional Opening metadata

VerifyValidator

Field Type Label Description
member_id uint64 required
is_verified bool required

WorkingGroupMetadata

Field Type Label Description
description string optional Group description text (md-formatted)
about string optional Group about text (md-formatted)
status string optional Current group status (expected to be 1-3 words)
status_message string optional Short status message associated with the status

WorkingGroupMetadataAction

Field Type Label Description
set_group_metadata SetGroupMetadata optional
add_upcoming_opening AddUpcomingOpening optional
remove_upcoming_opening RemoveUpcomingOpening optional

OpeningMetadata.ApplicationFormQuestion.InputType

Name Number Description
TEXTAREA 0
TEXT 1

Scalar Value Types

.proto Type Notes C++ Java Python Go C# PHP Ruby
double double double float float64 double float Float
float float float float float32 float float Float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int int32 int integer Bignum or Fixnum (as required)
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long int64 long integer/string Bignum
uint32 Uses variable-length encoding. uint32 int int/long uint32 uint integer Bignum or Fixnum (as required)
uint64 Uses variable-length encoding. uint64 long int/long uint64 ulong integer/string Bignum or Fixnum (as required)
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int int32 int integer Bignum or Fixnum (as required)
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long int64 long integer/string Bignum
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int uint32 uint integer Bignum or Fixnum (as required)
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long uint64 ulong integer/string Bignum
sfixed32 Always four bytes. int32 int int int32 int integer Bignum or Fixnum (as required)
sfixed64 Always eight bytes. int64 long int/long int64 long integer/string Bignum
bool bool boolean boolean bool bool boolean TrueClass/FalseClass
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode string string string String (UTF-8)
bytes May contain any arbitrary sequence of bytes. string ByteString str []byte ByteString string String (ASCII-8BIT)

Referencing Assets

Applications that process messages that contain a uint32 field that references an asset such as a cover photo or video, should interpret this value as a zero based index into an array/vector that is received external (out of band) to the protobuf message.

Example in context of query-node processing the runtime event VideoCreated

// Runtime event associated with creating a Video
VideoCreated(video_id: VideoId, video: Video, assets: Vec<NewAsset>, params: VideoCreationParameters)

struct VideoCreationParameters {
  in_category: VideoCategoryId,
  // binary serialized VideoMetadata protobuf message
  meta: Vec<u8>,
}

// suppose assets is a vector of two elements. This is the "out of band" array being referenced by the VideoMetadata message
assets = [
    NewAsset::Uri("https://mydomain.net/thumbnail.png"),
    NewAsset::Upload({
       content_id,
       ipfs_hash,
       size,
       ...
    }),
];

meta = VideoMetadata {
    ...
    // refers to second element: assets[1] which is being uploaded to the storage system
    video: 1,
    // refers to the first element assets[0] which is being referneced by a url string.
    thumbnail_photo: 0,
    ...
};