Variable Definitions

From OIP Wiki
Jump to: navigation, search

Commonly used Variables

the following terms are used in many different kinds of OIP messages:

oip###
  • top-level object key

The top key in the message defines the version of the OIP Specification which was used in publishing this message. Currently this is oip-041. The next release, oip042, will change this key slightly by removing the hyphen.

register/pub/edit/transfer/deactivate
  • second-level object key

The next key defines what kind of action this message should cause - for example, a register message is used to register users in the index as publishers, retailers, promoters, autominers or autominer pools. A pub message is used to publish something into the index, an edit message is used to patch something previously added to the index, transfer is used to transfer ownership/signing authority of something in the index to a new owner, and deactivate messages are used to tell the index to remove an artifact that user had previously published.

pub/artifact/retailer/promoter/autominer/autominer-pool
  • third-level object key

The next key defines what kind of object this message should apply the previous key's action to. For example, if the previous key was register or edit, this one will be artifact, pub, retailer, promoter, autominer or autominer-pool. If the previous key was pub, this one will be artifact or historypoint, if it was transfer or deactivate, this one will be artifact or pub.

signature
  • third-level key-value pair (value is a string)

A piece of text is provided to a Flo blockchain wallet and signed by a given Flo key, the resulting signature is included in blockchain messages in order to verify that they were generated by the same party who registered that Flo key in an earlier registration message. Each message type has its own signature recipe, they can be seen at the following links:

  • artifact: publish | edit | reassign | deactivate
  • publisher: register | edit
  • retailer: register | edit
  • promoter: register | edit
  • autominer: register | edit
  • autominer-pool: register | edit
timestamp
  • fourth-level key-value pair (value is an integer)

The current Unixtime (a system for describing a point in time, defined as the number of seconds that have elapsed since 00:00:00 Coordinated Universal Time (UTC), Thursday, 1 January 1970, minus the number of leap seconds that have taken place since then.)

Note: this should be expressed in seconds (10 digits), and not milliseconds (13 digits).

Registration Variables

Commonly used registration variables; the following terms are used in more than one kind of registration message.

alias
  • fourth-level key-value pair (value is a string)

A non unique name, used in registration messages for Publishers, Retailers, Promoters, Autominers and Autominer-Pools.

address
  • fourth-level key-value pair (value is a string)

A Flo blockchain address, used in registration messages for Publishers, Retailers, Promoters, Autominers and Autominer-Pools.

info
  • fourth-level object key

Contains a list of key value pairs that describe or contextualize a particular artifact, publisher, retailer, promoter, autominer or autominer-pool. Specific key-value pairs will be described in their appropriate sections below.

verification
  • fourth-level object key

This object consists of key-value pairs which are used for social-media verification purposes, like a verified publisher name.

It is found in the following message types:

  • register:pub
  • register:retailer
  • register:promoter
  • register:autominer
  • register:autominer-pool
  • edit:pub
  • edit:retailer
  • edit:promoter
  • edit:autominer
  • edit:autominer-pool
 IMDB/MusicBrainz/Twitter/Facebook
  • fifth-level key-value pairs (values are strings)

The URL of a specially formatted verification message stored on a social media platform, used to confirm that a publisher, retailer, promoter, autominer or pool is the same party that controls a particular social media account.

Register Publisher Variables

authorized
  • fourth-level array (values are strings)

A list of Addresses which are authorized to make changes to this Publisher's Artifacts.

emailmd5
  • fifth-level key-value pair, inside of the info object (value is a string)

The md5 hash of a given email address. Used with the Gravatar avatar hosting service to let users associate themselves with an avatar without needing to host the image file within a decentralized network.

avatarNetwork
  • fifth-level key-value pair, inside of the info object (value is a string)

If a user does not wish to rely on a centrally managed avatar host like Gravatar, they can reference an image file hosted on a peer to peer network. This value identifies the name of the network, used in conjunction with avatar.

Values currently supported:

  • IPFS

Values with support currently planned:

  • BittorrentMainline
avatar
  • fifth-level key-value pair, inside of the info object (value is a string)

If a user does not wish to rely on a centrally managed avatar host like Gravatar, they can reference an image file hosted on a peer to peer network. This value identifies the actual content address of the file itself, used in conjunction with avatarNetwork.

headerImageNetwork
  • fifth-level key-value pair, inside of the info object (value is a string)

If a user wishes to, they can use an image file hosted on a peer to peer network for their Publisher Profile's "header" or "banner" image. This value identifies the name of the network, used in conjunction with headerImage.

Values currently supported:

  • IPFS

Values with support currently planned:

  • BittorrentMainline
headerImage
  • fifth-level key-value pair, inside of the info object (value is a string)

If a user wishes to, they can use an image file hosted on a peer to peer network for their Publisher Profile's "header" or "banner" image. This variable defines the actual content address of the file itself, used in conjunction with headerImageNetwork.

bitmessage
  • fifth-level key-value pair, inside of the info object (value is a string)

Getting deprecated, ignore.

signature (register publisher message)
  • third-level key-value pair (value is a string)

A piece of text is provided to a Flo blockchain wallet and signed by a given Flo key, the resulting signature is included in blockchain messages in order to verify that they were generated by the same party who registered that Flo key in an earlier registration message. Signature recipe is:

  • address-alias-timestamp

Register Retailer Variables

addresses
  • fourth-level object key

This object consists of key-value pairs which identify which public key addresses this retailer can receive payments to.

shortMWcoins
  • fourth-level object key

This object consists of key-value pairs which identify which public key addresses this retailer can receive payments to.

Register Promoter Variables

Register Autominer Variables

Register Autominer-Pool Variables

Artifact Variables

publisher

(Publisher Address) A string. The ECDSA public key registered by the Publisher.

type

A string. The media type of the primary piece of content in a given Artifact.

Examples: Video-Basic, Video-Movie, Audio-Song, Audio-Album, Text-PDF

Complete List of All Media Types

title

A string. The Publishers name for the Artifact; should encompass the entire Artifact. Title's must be unique amongst a Publisher's Artifacts; in other words, each publisher can have only one artifact with any given Title at any point in time.

description

A string. Self explanatory, but note that this is a required field for all Artifacts.

year

An integer. The year that this piece of content was first released.

artist

A string. The professional name of the artist who created the piece of content.

company

A string. The name of the label, studio or production company responsible for the piece of content.

tags

An array of strings.

Genre

Info about Genres to be added

fiat

A string. The ISO currency designator for the fiat money in which the publisher is expressing their pricing terms. At this time, most common is “USD.”

Complete list of designators

scale

The ratio applied to the integer values of commercial and tipping prices, along with the value from the fiat field, to arrive at display prices. Most common at this time is 1000:1. Combining this with the value from the fiat field means that a value of 1000:1 should be interpreted as 1000 units to 1 US Dollar

addresses

An array of cryptocurrency payment addresses. Each shall be identified by the three letter identifier of the particular blockchain. For example, "btc" for Bitcoin, "ltc" for Litecoin, "eth" for Ethereum, and so on. Any number of addresses can be included.

tokens

An array of tokenly tokens, as ALL CAPS strings and integers. ***EXPLAIN THIS***

network

A string. The name of the file transport network where the file can be found. Default value shall be IPFS, eventually BitTorrent will likely also be commonly used.

location

A string. The location address where the file can be found within the designated network.

disBuy

(Disallow Buying) A boolean value. If "true", this file will not be allowed to be purchased, only played.

disPlay

(Disallow Playing) A boolean value. If "true", this file will not be allowed to be played, only purchased.

dName

(Display Name) A string. The name that should be used to label the file.

fName

(File Name) A strong. The name of the file itself, including its file extension. Used along with network and location to retrieve the file for playback or downloading.

duration

An Integer representing the playtime of the file, in seconds.

fSize

An Integer representing the file size, in bytes.

sugTip

(Suggested Tip) An array of integers. As many as three values.

sugPlay

(Suggested Play) This is the full price to play the piece of content, think "manufacturers suggested retail price.” An integer value, with the scale and fiat values applied in order to display the retail price. For example, a value of 5, with a scale of 1000:1 and fiat of USD would be displayed as 5*1/1000 USD => $0.005, or half of a penny.

minPlay

(Minimum Play) The lowest allowed price to play the piece of content. Used when a retailer is having a sale or promotion. An integer value with scale and fiat values applied to determine price.

sugBuy

(Suggested Buy) The full price to buy the piece of content. Currently buying a piece of content means downloading the file, but soon it will mean buying a token that represents playback rights (currently planning to use Tokenly’s protocol - it functions as Ultra Violet on a blockchain).- aren’t doing to do this default, they have to ask/pay for it An integer value with scale and fiat values applied to determine price.

minBuy

(Minimum Buy) The lowest allowed price to buy a piece of content. Used when a retailer is having a sale or promotion. An integer value with scale and fiat values applied to determine price.

disPer

(Discount Percent) The maximum percent discount allowed for a piece of content, applied to the #SugPlay and/or [#SugBuy]. Used as an alternative to MinPlay and MinBuy when the publisher has no need to define both individually.

retailer

The percent of commercial (or voluntary tipping) value paid to retailers who facilitate relevant commercial (or voluntary tipping) activity. An integer value of 100 or less, can be 0 or omitted. Can be used with non-commercial artifacts (tip-only) to financially incentivize suggestion of high quality free content. This percent is applied to the total transaction price after sales/promotions discounts have been applied. Example: A song priced at $1 (sug)/$0.70 (min) to buy, and $0.015 (sug)/$0.01 (min) to play, offering a 20% retailer cut. The maximum a retailer can discount each piece of content is limited by its own publisher - for this example, any sale would be limited to 30% off for purchases, and 33% for plays.

  • Any normal day, a purchase will result in $0.80 going to the publisher and $0.20 going to the retailer.
  • If the retailer has a 10% sale, a purchase will result in $0.72 going to the publisher and $0.18 going to the retailer, and a play would result in $0.0108 going to the publisher and $0.0027 going to the retailer.

promo

Similar to the Amazon Affiliates program. The percent of commercial (or voluntary tipping) value paid to individual content promoters who drive relevant payment activity. An integer value of 100 or less, can be 0 or omitted. Can be used with non-commercial artifacts (tip-only) to financially incentivize promotion of high quality free content. * gets percentage based on price paid after discounts have been applied.

ptpFT

(Pin to Play Free Threshold) The number of nodes at any given time that can get free access to a file in exchange for pinning (aka: seeding) the file. Creates the option for publishers offer limited access to free content in exchange for file distribution which eliminates the publisher’s file storage and distribution costs. A positive integer value, can be 0 or omitted. We expect a number of market determined mean values will develop, depending on the type of content and target audience. We estimate popular albums of high bitrate MP3s will have an ideal ptpFT value of ~8, whereas a long video or movie will have an ideal value of ~20. *We should add to tested, or show our test or something

ptpDT

(Pin to Play Discount Threshold) The number of nodes at any given time, past the threshold of those getting free access, that can get discounted access in exchange for pinning the file. Even when a file has a decent swarm of nodes pinning it (estimated: 10-20), there is added (although diminishing) benefit from more nodes in a swarm. The Pay to Play Discount Threshold provides an incentive for end users to participate in the "pin to play" system because some files will be free and some will be discounted. A positive integer value, can be 0 or omitted, or can be -1 if the publisher wishes to put no limits on the number of nodes receiving this discount.

ptpDP

(Pin to Play Discount Percent): An integer value of 100 or less, can be 0 or omitted, only relevant if artifact contains a value for ptpDT. * percent applied to total transaction amount after discount has been applied.

signature

A string. Result of signing location-publisherAddress-timestamp with the private key corresponding to the publisherAddress