Topic: GLBSE VOP protocol....specifcation (Read 1294 times)

All functions return base64 encoded strings from the server, nothing is sent non-encoded.
All server resources accept only http post requests.

All requests to the server have 2 post fields
"data", which is base64 encoded json
"signature", which is the sha512 RSA signature of the data field

data is a json hash, and always contains the elements:
"userid", which is the users id (given during registration)
"nonce", a unique random number that must be sent with each request.

These are the only required two elements in data.

Errors
All requests may return errors from the server if there is a problem, which are usually plain text strings.
Errors are caused by internal server errors, wrong input, failed verification, accounts that don't balance,
or attempting to buy or withdraw more than is available in the account.

Register
url:/register
This is a special function, 
in that it does not need to be signed by the client (how can it be verified, the users new public key isn't on the server yet).
It's data field (base64 encoded json) also DOES NOT contain the users userid or nonce like all other requests.

Send only a single post field, data. This is base64 encoded json with the elements:
"public_key" which contains a string of the users public key.

This function will return base64 encoded hash with the key "public_id" which is the users public id.
{"public_id":}

Account balance
url:/account/balance

no extra parameters needed beyond default
returns json string {"balance":} with the users balance

Deposit
url:/account/deposit
no extra parameters needed beyond default
returns json string {"address":} with a bitcoin address to deposit to

Withdraw
url:/account/withdraw

extra data elements:
"amount", a positive integer representing the full 64bit int bitcoin value to be withdraw (e.g. 1btc = 100000000)
"address", a valid bitcoin address to deposit to.
returns json string {"balance":} with the users balance

Portfolio
url:/account/asset/list
lists all the assets the user has.
no extra parameters needed beyond default
returns json string {"assets":}
assets contains a hash of asset id's/names which then also have another hash {"balance:"} with the actual number of assets held

Asset
url:/asset
returns the details of a particular asset
extra data elements:
"asset_id"
returns json string
{"asset":asset_id,"max_bid":max,"min_ask":min,"issues":quantity_issued,"last_trade":price_last_traded_at}

Asset Depth
url:/asset/depth
returns the buy's and sells for an asset
extra data elements:
"asset_id"
returns json string, containing arrays with quantity:price sub arrays for each bid or ask 
{"asks":[[quantity,price]],"bids":[[quantity,price]]} 

Buy/Sell
url:/market/buy, url:/market/sell
place a buy/sell order for an asset on the market
extra data elements:
"asset" which is the asset id
"quantity", a positive integer
"price", a positive integer representing the full 64bit int bitcoin value to be withdraw (e.g. 1btc = 100000000) to trade each unit of asset
returns json string, containing either the order number (which can be used to watch or cancel an order later), or the market transaction number
{"transactions":[transaction_ids]}
{"market_order":market_order_id}

Transfer
url:/account/asset/transfer
Transfers assets from one account to another
extra data elements:
"asset" the asset_id
"quantity" a positive integer
"to_account", the public_id of the account that will receive the asset
returns json string
{"balance":assets_balance}

Orders
url:/market/orders
no extra parameters needed beyond default
returns json string
{"orders":order_id}
order_id=>{"status":order_status,"order":buy_or_sell,"quantity":quantity,"price":price,"asset":asset_id,"timestamp":unix_timestamp}

Cancel Order
url:/market/order/cancel
Each order listed in market orders should have a cancel button or link beside it.
extran data elements:
"order_id"
returns json string
{"result":result} #"result should be "canceled" if succesful

Bitcoin/Asset/Market history
takes no additional arguments

url:/history/assets
returns: 
{"transactions":transaction_id}
transaction_id=>{"quantity":quantity,"type":order_type,"timestamp":unix_timestamp,"asset_id":asset_id}

url:/history/bitcoin
returns:
{"transactions":transaction_id}
transaction_id=>{"amount":amount,"type":type,"address":bitcoin_address(sometimes empty,"timestamp":unix_timestamp}
 
url:/history/market
returns:
{"transactions":transaction_id}
transaction_id=>{"price":price,"quantity":quantity,"timestamp":unix_timestamp,"asset":asset_id,"type":order_type} 

Motions
url:/motions
no extra parameters needed beyond default, returns a list of motions the user can vote on
returns:
{"motion_ids":[motion_id,motion_id.....]}

clicking on a motion should bring up the details of the motion
url:/asset/motion
extra data elements:
"motion_id"
returns:
{"motion_id":motion_id,"text":motions_text,"closes":date_motion_closes("%d-%m-%y")}

each motion should have a yes or no button on it to allow the user to vote on the motion
url:/vote
extra data elements:
"vote_id", same as motion_id in above
"vote", can be either "yes" or "no"
returns:
{"result":true}
user can change their vote as many times as they want before the vote/motion closes

each vote/motion should also have a link to "Tally" beside it, that show the voting count.
url:/vote/tally
extra data elements:
"motion_id", the motion id the user wants to know the result of
returns:
{"yea":number_of_yes_votes,"nay":number_of_no_votes}

New Asset
url:/account/asset/new
creates a new asset
extra data elements:
"contract", the gpg signed xml contract, for all intents and purposes this should just be a textfile
"contract_signature", the rsa private key signature(base64 encoded) of the contract text in "contract"
returns:
{"contract":the_submited_contract,"asset_id":asset_id_of_new_asset,"balance":users_bitcoin_balance}

Issue Asset
url:/account/asset/issue
issues asset
extra data elements:
"asset_id"
"quantity", a positive integer
returns:
{"balance":number_of_assets_in_account}

Register Ticker
url:/register/ticker
give a new ticker symbol to an asset
extra data elements:
"asset_id"
"ticker" is the symbol itself, must be less than 50 chars and contains only 'a'..'z','A'..'Z', '0'..'9' characters (this may change)
returns:
{"ticker":new_ticker}

New Motion
url:/vote/new
creates a new motion to be voted on by shareholders.
extra data elements:
"asset_id"
"motion", the actual text of the motion to be voted on. This can be taken from a form field or as the text read from a file.
"date", the date of expiry(when voting ends) in the format "%d-%m-%y" or dd-mm-yy
returns:
{"vote_id":motion_vote_id}

Pay asset holders
url:/asset/pay
To pay holders of the asset a dividend
extra data elements:
"asset_id"
"amount", a positive integer representing the full 64bit int bitcoin value to be withdraw (e.g. 1btc = 100000000) 
returns:
{"assets_paid":number_of_assets_paid,"amount":total_amount,"payment_per_share":pps}