Message protocol

From OIP Wiki
Revision as of 00:50, 3 February 2018 by Bitspill (talk | contribs)
Jump to: navigation, search

Contents

Mining Pool Messages

Autominer Pool Historian Datapoint

A string, stored in the block reward (coinbase) transaction comment. The pieces of data included are used to estimate the cost to mine this particular block, by multiplying the current average cost to rent a sCrypt miner on MiningRigRentals.com (more sources with time) by the pool's hashrate and dividing by the block reward. The full formula can be found in the specification.

Please note: there should not be spaces of any sort between each semi-colon and piece of data when sent to the blockchain, carriage returns are used here for page formatting purposes only.

The above schema will be implemented soon into the OIP Daemon and Alexandria's hosted endpoints. Expand this section to see the schema currently in use for Historian Datapoints

Autominer Block Reward

A string, stored in the transaction comment attached to the block reward payout sendmany transactions sent by autominer pools. It is used to help establish the chain of custody of mined tokens, by delineating from which blocks a particular token payout comes from.

In instances in which only one miner is receiving their payout, from a single won block, the message format will look like this:

{
oip042:
pub:
abr:
poolFloAddress:
block:
amount:
signature
}

In instances in which a single miner is receiving their payout, from a series of won blocks, the message will look like this:

And in instances in which a variety of miners are receiving payouts from a series of won blocks, the message will look like this:

Please note: there should not be spaces of any sort between each semi-colon and piece of data when sent to the blockchain, carriage returns are used here for page formatting purposes only.

Multipart Messages

All of the below blockchain messages are stored as plaintext in one or more transaction comments. If the total message length is larger than the 528 byte tx-comments currently supported by Florincoin, then the message will be split up into a Multipart message.

You can find information on how Multipart messages are formed here.

Index Manipulation Messages

Register/Publish Edit Transfer Control Deactivate
Publishers Publisher Register Publisher Edit
Artifacts Artifact Publish Artifact Edit Artifact Transfer Artifact Deactivate
Retailers Retailer Register Retailer Edit
Promoters Promoter Register Promoter Edit
Autominers Autominer Register Autominer Edit
Autominer-Pools Autominer-Pool Register Autominer-Pool Edit

Publisher Register

 {
 	"oip042": {
 		"register": {
 			"pub": {
 				"alias": "string",
 				"address": "string",
 				"timestamp": integer,
 				"authorized": ["string", "string"],
 				"extraInfo": {
 					"emailmd5": "string",
 					"avatarNetwork": "string",
 					"avatar": "string",
 					"headerImageNetwork": "string",
 					"headerImage": "string",
 					"bitmessage": "string"
 				},
 				"verification": {
 					"IMDB": "string",
 					"MusicBrainz": "string",
 					"Twitter": "string",
 					"Facebook": "string"
 				}
 			},
 			"signature": "string"
 		}
 	}
 }

Anyone can use Alexandria's hosted API to get a list of all registered Publishers, or search for one in particular. Since it uses an RPC connection to a FLO wallet and would have total control over the keys in that wallet, using the API to Register a New Publisher can only be done against localhost - in other words it can only be used by decentralized users running a full node of the Flo blockchain and the OIP Daemon application. Web developers can use the node.js application oip-js to sign and send a Register Publisher message for individual users with separate web hosted wallets.

The above schema will be implemented soon into the OIP Daemon and Alexandria's hosted endpoints. Expand this section to see the schema currently in use for publisher register:

{
	"publisher-data": {
		"alexandria-publisher": {
			"name": "string",
			"address": "string",
			"timestamp": integer,
			"emailmd5": "string",
			"bitmessage": "string",
			},
		"signature": "string"
		},
	"txid": "string",
	"block": string
}

Publisher Edit

To view the JSON schema for Publisher Edit, click Expand ->

{
 	"oip042": {
 		"edit": {
 			"pub": {
 				"address": "string",
 				"timestamp": int,
 				"patch": {
 				// Squashed Edit of JSON Patch Schema https://tools.ietf.org/html/rfc6902
 				}
 			}
 		}
 	},
 	"signature": "string"
}

Artifact Publish

To view the JSON schema for Artifact Publishing, click Expand ->

{
 	"oip042": {
 		"publish": {
 			"artifact": {
            "publisher": "string",
            "timestamp": 10 digit int,
            "type": "string",
            "info":{
                "title": "string",
                "description": "string",
                "year": 4 digit int,
                "extraInfo":{
                    "artist": "string",
                    "company": "string",
                    "tags":[
                        "string",
                        "string"
                    ]
                }
            },
            "payment":{
                "fiat": "string",
                "scale": int,
                "sugTip":[
                    int,
                    int,
                    int
                    ],
                "addresses": {
                    "three letter string":"string",
                    "three letter string":"string"
                },
                "tokens": {
                    "STRING": int,
                    "STRING": int
                }
            },
            "storage":{
                "network": "string",
                "location": "string,
                "files":[
                    {
                        "disBuy": boolean,
                        "disPlay": boolean,
                        "dName": "string",
                        "duration": int,
                        "fName": "string",
                        "fSize": int,
                        "sugPlay": "int",
                        "minPlay": "int",
                        "sugBuy": "int",
                        "minBuy": "int",
                        "disPer": "int",
                        "promo": "int",
                        "retail": "int",
                        "ptpFT": int,
                        "ptpDT": int,
                        "ptpDA": int,
                        "type": "string",
                        "tokenlyID": "string"
                    }
                ]
            },
        "signature": "string"
    }
}

A list of Published Artifacts can be found at Alexandria's hosted API endpoint

Artifact Edit

To view the JSON schema for Artifact Edits, click Expand ->

{
    "oip-041": {
        "editArtifact": {
            "txid": "string",
            "timestamp": int,
            "patch": {
                // Squashed Edit of JSON Patch Schema https://tools.ietf.org/html/rfc6902
            }
        }
    },
    "signature": "string"
}

Artifact Transfer

To view the JSON schema for Artifact Transfers, click Expand ->

{
    "oip-041": {
    "transferArtifact": {
        "txid": "string",
            "to": "string",
            "from": "string",
            "timestamp": int
        },
        "signature": "string"
    }
}

Artifact Deactivate

To view the JSON schema for Artifact Deactivation, click Expand ->

{
    "oip-041": {
        "deactivateArtifact": {
            "txid": "string",
            "timestamp": int
        },
        "signature": "string"
    }
}

Retailer Register

Plaintext data, stored in a transaction comment.

To view the JSON schema for Register Retailer, click Expand ->

{
    "oip-041": {
        "retailer": {
            "FLOaddress": "string",
            "FLOaddress": "string",
            "http-url": "string",
            "version": 2,
            "extraInfo": {
                "name": "string",
                "minimum-share": int
            },
            "verification": {
                "twitter": "string",
                "facebook": "string"
            }
        },
        "signature": "string"
    }
}

deprecated Register Retailer schema

A list of Registered Retailers can be found at Alexandria's hosted API endpoint

Promoter Register

To view the JSON schema for Register Promoter, click Expand ->

{  
    "oip-041":{  
        "promoter":{  
            "BTCaddress":"string",
            "LTCaddress":"string",
            "FLOaddress":"string",
            "version": 2,
            "extraInfo": {
                "name": "string",
                "minimum-share": int
            },
            "verification":{  
                "facebook":"string",
                "twitter":"string"
            }
        },
        "signature":"string"
    }
}

deprecated Register Promoter schema

A list of Registered Promoters can be found at Alexandria's hosted API endpoint

Autominer Register

To view the JSON schema for Register Autominer, click Expand ->

{
    "oip-041": {
        "autominer": {
            "FLOaddress": "string",
            "BTCaddress": "string",
            "endpointURL": "string",
            "version": 2
        },
        "signature": "string"
    }
}

deprecated Register Autominer schema

A list of Registered Autominers can be found at Alexandria's hosted API endpoint

Autominer Pool Register

To view the JSON schema for Register Autominer Pool, click Expand ->

{
    "oip-041": {
        "autominerPool": {
            "FLOaddress": "string",
            "webURL": "string",
            "PoolName": "string",
            "TargetMargin": integer,
            "PoolShare": integer,
            "version": 2
        },
        "signature": "string"
    }
}

deprecated Register Autominer Pool schema

A list of Registered Autominer Pools can be found at Alexandria's hosted API endpoint

Key Definitions

Commonly used

These object keys and key-value pairs are used in multiple 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/publish/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 publish 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

These object keys and key-value pairs are used in registration messages.

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

These object keys and key-value pairs are used publisher registration messages only.

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

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

Register Autominer

Register Autominer-Pool

Artifacts

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