Protocol Documentation

Table of Contents

• proto/App.proto

  • AppAction

  • AppActionMetadata

  • AppAction.ActionType

  • AppAction.CreatorType

• proto/Bounty.proto

  • BountyMetadata
  • BountyWorkData

• proto/Channel.proto

  • ChannelMetadata

• proto/ChannelPayouts.proto

  • ChannelPayoutsMetadata

  • ChannelPayoutsMetadata.Body

  • ChannelPayoutsMetadata.Body.ChannelPayoutProof

  • ChannelPayoutsMetadata.Body.ChannelPayoutProof.ProofElement

  • ChannelPayoutsMetadata.Header

  • ChannelPayoutsMetadata.Header.ChannelPayoutByteOffset

  • ChannelPayoutsMetadata.Body.ChannelPayoutProof.Side

• proto/Council.proto

  • CouncilCandidacyNoteMetadata

• proto/Forum.proto

  • ForumPostMetadata
  • ForumThreadMetadata

• proto/Membership.proto

  • MembershipMetadata

  • MembershipMetadata.ExternalResource

  • MembershipMetadata.ExternalResource.ResourceType

• proto/Metaprotocol.proto

  • AppMetadata

  • BanOrUnbanMemberFromChannel

  • ChannelModeratorRemarked

  • ChannelOwnerRemarked

  • CreateApp

  • CreateComment

  • CreateVideoCategory

  • DeleteComment

  • EditComment

  • MakeChannelPayment

  • MemberRemarked

  • ModerateComment

  • PinOrUnpinComment

  • ReactComment

  • ReactVideo

  • UpdateApp

  • VideoReactionsPreference

  • BanOrUnbanMemberFromChannel.Option

  • PinOrUnpinComment.Option

  • ReactVideo.Reaction

  • VideoReactionsPreference.Option

• proto/Person.proto

  • PersonMetadata

• proto/ProposalsDiscussion.proto

  • ProposalsDiscussionPostMetadata

• proto/Series.proto

  • SeasonMetadata
  • SeriesMetadata

• proto/Storage.proto

  • DistributionBucketFamilyMetadata

  • DistributionBucketOperatorMetadata

  • GeoCoordiantes

  • GeographicalArea

  • NodeLocationMetadata

  • StorageBucketOperatorMetadata

  • GeographicalArea.Continent

• proto/Token.proto

  • Benefit
  • CreatorTokenIssuerRemarked
  • SaleMetadata
  • TokenMetadata
  • UpdateTokenMetadata

• proto/Video.proto

  • ContentMetadata
  • License
  • MediaType
  • PublishedBeforeJoystream
  • SubtitleMetadata
  • VideoMetadata

• proto/WorkingGroups.proto

  • AddUpcomingOpening

  • ApplicationMetadata

  • ModeratePost

  • OpeningMetadata

  • OpeningMetadata.ApplicationFormQuestion

  • RemarkMetadataAction

  • RemoveUpcomingOpening

  • SetGroupMetadata

  • UpcomingOpeningMetadata

  • VerifyValidator

  • WorkingGroupMetadata

  • WorkingGroupMetadataAction

  • OpeningMetadata.ApplicationFormQuestion.InputType

• Scalar Value Types

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,
    ...
};