Source

git

git clone https://lohoris@bitbucket.org/lohoris/nullgame.git

API calls

balance functions

• getbalance ($user)

Returns an array including

• "gold": the amount of gold free
• "lock": the amount of gold locked

lock and unlock functions

• lock_gold ($user, $amount)
• unlock_gold ($user, $amount)
• unlock_and_move_gold ($user_from, $user_to, $amount)

They lock, unlock and "unlock and move" gold. As you can notice, there is no "move" function: you always have to lock it before moving it.

They return true in case of success.

token functions

• bind_token ($_user, $token)

Checks if a user's token is legit.

Returns true in case of success.

Token format

The token must be in the following format:

• an int for the currency_id, which will be a constant provided by us
• a :
• an int for the user_id, which identifies the user in your game or site
• a :
• an hex encoded string representing 64 bytes, which will be the unsalted token

You will have to store a 64 byte salt and store the token salted (prepending the salt to the password).

Gold rules

Gold format

You will store user's gold as an integer, never as a floating point value. You may then represent it visually with decimal units if you like, but all the communication, storing and operations will have to be on integers only.

Honouring locks

You may create or destroy gold as you wish, but you will always have to honour locked gold: never create or destroy locked gold, and always honour lock (if the user has enough funds), unlock and move requests.

Handling multiple characters

Even if your game has multiple shards or multiple characters per user, this will have to be transparent to us, i.e. we will interface to "the game as a whole" and to "the user as a whole": it will be up to you to allow the user to move freely her gold among her characters or shards.

Our advice in that case is to enable the user to "move gold to storage" from any of her characters, let us see that gold, and have her move it back to any of her characters using the same procedure.

(my personal advice would be to avoid sharding the game in the first place)

Handling multiple trading sites

In case you want to support more than one trading site, always keep separate lock columns and separate tokens! Never share one lock column or one token between more than one site! You should instead share the same gold, though.

Error rules

Logging

Please log any error, as without logs it will be difficult for us to solve any eventual problem which might arise.

Fixing

Please bear in mind that bitcoins are a decentralised currency which cannot be created at will and is not under our control, so in case of an unrecoverable error, you will have to err to the site of creating gold for the user.