Skip to content

'Kogs' game rpc specification

Jump to bottom
dimxy edited this page Jul 19, 2020 · 28 revisions

KOGS game blockchain rpcs description

doc version: v0.3.5 (draft)

Corrections

0.3.5

updated for the last rpc additions and changes, updated game rpc example flow

0.3.4

in kogsgamelist added a param playerid

0.3.3

example section: kogscreateplayer is called by the player

Introduction

This doc contains a description of an rpc for komodo blockchain Antara (cryptocondition) module for game 'Kogs'. Kogs is a computerized version of the Pogs game, which was popular in USA, in 199x. 'Kogs' is a alias name of Pogs which stored in the blockchain as tokens. This Kogs blockchain module rpc provides services for Kogs game GUI, for managing blockchain-level game objects: players, games, tokens which store kogs, slammers, packs, containers, etc.

Currently implemented Kogs blockchain-level game objects

Only basic functionality is defined on this initial version. Each kog or slammer instance is a non-fungible token. Implemented objects for this stage:

  • player
  • kog
  • slammer
  • container
  • pack (with hidden encrypted content)
  • gameconfig
  • game

No wager, chips and bundles at this stage.

The system architecture is supposed to have a web site and player's desktop and mobile applications (GUI part) The web site is supposed to provide the game 'lobby' functionality:

  • registering users
  • showing kogs, slammers and packs data from the blockchain
  • name-to-address resolution to access player queues (TODO: maybe this would not be needed if we could store this data in mempool)
  • selling packs of kogs and slammers

Part of the game functionality is implemented in the GUI part of the game:

  • queuing messages in off-chain queue system to find out matching players. (TODO: maybe this could be done on chain...)
  • finding matching players in queue and starting a game with some chain rpc
  • managing kog stacks (purely off chain)
  • executing slams, calculating slam results and publishing them to the chain with some chain rpc

RPC description

Some notes about the RPC:

  • Most of the rpc methods return one or more transactions in hexademical encoding to send them to the chain with sendrawtransaction rpc call. And sendrawtransaction call would return the txid of the just sent transaction that in most cases is the id of the created object (kog, slammer, gameconfig, game etc)
  • Usually one or more params are required with 'id' at its end (packid, tokenid etc). This is the creation transaction id of the required object or NFT.
  • Some params are passed as cmd line strings, some as json objects in '{...}' quotes and brackets (json is to allow optional params).
  • The chain komodod command line should have set the param 'ac_kogsgame=1' and '-kogssyspk=' which defines the system user key who can create kogs, slammers, gameconfigs. Also -ac_cc= param should be set to value >= 2 to enable cc modules in the chain.

The currently implemented RPC descriptions are in this section.

System (admin) RPCs

kogscreateplayer

kogscreateplayer name desc {player-params}
Creates a player object with the passed params.
Limitation: this method does not allow to create more than one player for one pk

??? Who should create the player object, the System User or the player himself?

kogscreatekogs

kogscreatekogs '{"kogs":[{"nameId":"name", "descriptionId":"desc", "imageId":"image-id", "setId":"set-id", "subsetId":"subset-id", "packId":"id"}, {...}]}'
Creates transactions for NFT with the passed params
packId param is optional Returns an array of token creation txns in hex [hextx1, hextx2,...]

kogscreateslammers

kogscreateslammers '{"slammers":[{"nameId":"name", "descriptionId":"desc", "imageId":"image-id", "setId":"set-id", "subsetId":"subset-id"}, {...}]}'
creates slammer NFT creation transactions with the passed params
returns an array of token creation txns in hex [hextx1, hextx2,...]

kogscreatepack

kogscreatepack name description packsize
creates a pack of the packsize

kogscreategameconfig

kogscreategameconfig name description '{ param1, param2, ... }'
creates game configuration.
returns game config tx in hex to send it to the chain.

kogsunsealpack

kogsunsealpack packid
Unseals a pack by burning it. It is supposed that the system user would create NFTs of the pack size and sends them to the pack owner.

A scenario for managing packs' content:

  • Before any pack creation the System User creates and remembers an encryption key of 32 byte and initialization vector of 32 byte.
  • The System User calls the 'kogscreatepack' rpc and passes the encryption key and ini vector as the params
  • The rpc decrypts all existing packs to get the list of the nfts in the packs
  • Then the rpc adds randomly the requested number of the nfts that are not in any pack the rpc creates a new pack tx and encrypts its content of the added nfts tokenids (the encryption key is not stored in the chain and is kept by the system user)
  • Upon purchasing the pack is sent (still encrypted) to the purchaser's address with the tokenfillask rpc
  • When the purchaser wants to unseal the pack he burns it with kogsburntoken rpc.
  • The the System User calls kogsunsealpack method for burned pack which decrypts pack content and create txns which send the pack's NFTs to the purchaser.

RPCs to remove objects (admin)

kogsremoveobject

kogsremoveobject creationtxid vout
removes the object from object list by spending its marker.

Player RPCs

kogsburntoken

kogsburntoken tokenid
burns a token by sending its value to the dead pubkey
This rpc is used by players to burn pack tokens. When a player burns a pack token, the System User unseals it.

kogscreatecontainer

kogscreatecontainer name desc playerid
Creates a container to store kogs in it for the player with playerid.

kogsaddkogstocontainer

kogsaddkogstocontainer containerid kogid1 kogid2 ...
Adds kogs to a container

kogsremovekogsfromcontainer

kogsremovekogsfromcontainer '{ "containerid":"id", "gameid":"id", "tokenids": [kogid1, kogid2] }'
Removes kogs from the container.
'gameid' is optional, passed if container is deposited to the started game and the system user wants to remove lost kogs.

kogsdeposittokens

kogsdepositcontainer gameid containerid slammerid
Deposits a container and a slammer to an active game

kogsadvertiseplayer

kogsadvertiseplayer '{"playerid": "id", "opts" : [ "playforkeeps", "playforfun", "playforwages" ] }'
Advertises a player to be ready for playing with one or mode game modes set

kogsstopadvertiseplayer

kogsstopadvertiseplayer playerid removes a playerid from the advertised players' list

kogsstartgame

kogsstartgame gameconfigid playerid1 playerid2 ...
Player starts a new game match with 2 or more players (including himself)
The params are:

  • gameconfigid - creation txid of gameconfig object
  • player pubkeys are passed.
    The method returns a game tx in hex to be sent to the chain by sendrawtransaction rpc.
    The system also passes the first turn to one of the players in the game.

Do we assume that the players are ready for a started new game? What if any of them are currently unavailable? Seems it should be a confirmation from all the players (like spending some game tx vouts). And if all did not confirm, the creator should be able to cancel the game. Now we have advertising rpc for that

Make a Slam RPC

kogsslamdata

kogsslamdata gameid playerid armheight armstrength
Sends slam data to the chain and triggers kogs flipping in the stack and the selection of the next player turn (by sending a baton to him).

Informational RPCs

Some informational methods returning arrays of game object ids:

  • kogsgamelist [playerid] - list gameids (creation txids) either all or in which playerid participates
  • kogsgameconfiglist - list gameconfigids
  • kogsplayerlist - lists players' tokenids
  • kogskoglist [my] - lists kogs' tokenids (if 'my' is present then only kogs on the mypk are shown)
  • kogsslammerlist [my] - lists slammers' tokenids (if 'my' is present then only slammers on the mypk are shown)
  • kogscontainerlist [my] - lists containers' tokenids (if 'my' is present then only containers on the mypk are shown)
  • kogspacklist - list packs' ids
  • kogsadvertisedplayerlist return list of advertised players

kogsobjectinfo

kogsobjectinfo objectid
Returns various info about the game object for the passed object creation id or tokenid: kog, slammer, pack, container, game, gameconfig instance.
See below an 'kogsobjectinfo' output example for a gameid.

RPCs to transfer, sell and buy tokens

There are methods to sell, buy or transfer tokens which are implemented in other Token and Assets Antara modules:

  • tokenask tokenid 1 price - offers the NFT for sell for the appointed price; returns tokenorder tx (for NFT tokens amount should always be equal to 1)
  • tokenfillask tokenorderid 1 - purchases the token for the offered price
  • tokentransfer tokenid pubkey 1 - sends the token to pubkey

RPC usage example

Before the usage we need to create a simple test komodo blockchain (KOGSCHAIN for this example) For this we could use komodo manual. Note that we should add additional chain parameters to the komodod command line (on each node): 'ac_kogsgame=1' and '-kogssyspk=' The ac_kogsgame=1 param should be added from the first ever start of the chain node The '-kogssyspk=' should be added after the first node run and the creation of the first node pubkey The rest chain 'ac_' parameters are not significant here.

The komodo manual for the chain creation: https://docs.komodoplatform.com/basic-docs/smart-chains/smart-chain-setup/installing-from-source.html

Now let's proceed to the example.

The System User Activity:

First, create game configuration (empty):

./komodo-cli -ac_name=KOGSCHAIN kogscreategameconfig gc1 some-desc '{ "KogsInContainer":4, "KogsInStack":4, "KogsToAdd":2, "MaxTurns":2, "HeightRanges":[{"Left":0,"Right":10, "UpperValue":50}, {"Left":10,"Right":100, "UpperValue":100}], "StrengthRanges":[{"Left":0,"Right":10, "UpperValue":50}, {"Left":10,"Right":100, "UpperValue":100}] }'

The params 'gc1', 'some-desc' are 'name' and 'description', they could be any strings.

This rpc call returns the created transaction (tx) in hex:

{
  "result": "success",
  "hextx": "010000000211c4a07ea62266a7a2b5085c9086ecef4f1cddbffee2e78c0520af24107cb09900000000484730440220776f675f5995c307f86e3c046e1d976ad58a65f56d90b2b910ce65cce7e39d49022044aee80f921c641f601b07095a04aeee1d39d59a50532df73ccab8f267ad539a01ffffffff15049c93fbc09fb3229c2282ce3d9398f513abc5c2deb42d4a5785d540a56cf30000000049483045022100ee901aa8233c869e0c4fb934a25dfd8c7cb535270d6c3a284965c3c1f160ee480220461397626d688bc6e11c3ccaf6485df8cf937a6cf32d43512c46351356e15a5901ffffffff030100000000000000302ea22c8020114a663be9cdd2e39802e0c78a36a6d50d8997dc21b481cd1dde290b3fc090d68103120c008203000401cc1027000000000000302ea22c8020394accc7110779971cd4d65b8cb1b3b6ed666021f8378b4bbcf1909ff8dd63c98103120c008203000401cc0000000000000000366a34f463010367633102636321035d3b0f2e98cf0fba19f80880ec7c08d770c6cf04aa5639bc57130d5ac54874db07f44d012800000000000000"
}

Use sendrawtransaction rpc to send the tx to the chain:

./komodo-cli -ac_name=KOGSCHAIN sendrawtransaction 010000000211c4a07ea62266a7a2b5085c9086ecef4f1cddbffee2e78c0520af24107cb09900000000484730440220776f675f5995c307f86e3c046e1d976ad58a65f56d90b2b910ce65cce7e39d49022044aee80f921c641f601b07095a04aeee1d39d59a50532df73ccab8f267ad539a01ffffffff15049c93fbc09fb3229c2282ce3d9398f513abc5c2deb42d4a5785d540a56cf30000000049483045022100ee901aa8233c869e0c4fb934a25dfd8c7cb535270d6c3a284965c3c1f160ee480220461397626d688bc6e11c3ccaf6485df8cf937a6cf32d43512c46351356e15a5901ffffffff030100000000000000302ea22c8020114a663be9cdd2e39802e0c78a36a6d50d8997dc21b481cd1dde290b3fc090d68103120c008203000401cc1027000000000000302ea22c8020394accc7110779971cd4d65b8cb1b3b6ed666021f8378b4bbcf1909ff8dd63c98103120c008203000401cc0000000000000000366a34f463010367633102636321035d3b0f2e98cf0fba19f80880ec7c08d770c6cf04aa5639bc57130d5ac54874db07f44d012800000000000000

The rpc returns:

1bef2ce809fb4b322a2b623033983e5135c677fded4d24111504089df495c552

this is the gameconfig transaction id (txid), which is also the 'gameconfigid'.

Note: this two-step transaction creation process is used in most RPCs which modify the chain state. These RPCs return one or several tx in hex, which to be sent to the chain with sendrawtransaction rpc.

List of gameconfigids may be obtained with this call:

./komodo-cli -ac_name=KOGSCHAIN kogsgameconfiglist

Create kogs and slammers

Create some kogs (note: only user with -kogssyspk pubkey can create kogs, slammers and packs):

./komodo-cli -ac_name=KOGSCHAIN kogscreatekogs '{"kogs":[{"nameId":"kog1", "descriptionId":"nft","imageId":"image-01","setId":"myset","subsetId":"mysubset"}, {"nameId":"kog2", "descriptionId":"nft","imageId":"image-02","setId":"myset","subsetId":"mysubset"}]}'

the call returns 2 txns in hex (to be sent via sendrawtransaction call)

Create more kogs (the system user):

./komodo-cli -ac_name=KOGSCHAIN kogscreatekogs '{"kogs":[{"nameId":"kog3", "descriptionId":"nft","imageId":"image-03","setId":"myset","subsetId":"mysubset"}, {"nameId":"kog4", "descriptionId":"nft","imageId":"image-04","setId":"myset","subsetId":"mysubset"}, ...]}'

Note: to play a game you need the number of kogs that is set in the gameconfig, for each player

Create slammers:

./komodo-cli -ac_name=KOGSCHAIN kogscreateslammers '{"slammers":[{"nameId":"slammer1", "descriptionId":"nft","imageId":"image-01","setId":"myset","subsetId":"mysubset"}, {"nameId":"slammer2", "descriptionId":"nft","imageId":"image-02","setId":"myset","subsetId":"mysubset"}, ...]}'

List of created kog or slammer ids maybe obtained with this rpc:

./komodo-cli -ac_name=KOGSCHAIN kogskoglist
./komodo-cli -ac_name=KOGSCHAIN kogsslammerlist

Sysuser sends kogs and slammers to players

Send to a user pubkey

./komodo-cli -ac_name=KOGSCHAIN tokentransfer kogid playerpk 1
./komodo-cli -ac_name=KOGSCHAIN tokentransfer slammerid playerpk 1

(You might also trade packs with tokenask and tokenfillask calls)

User, who received kogs and slammers, might list his tokens:

./komodo-cli -ac_name=KOGSCHAIN kogskoglist my
./komodo-cli -ac_name=KOGSCHAIN kogsslammerlist my

Note: pack does not support adding slammers so currently the system user might just send slammer tokens with tokentransfer or trade them via tokenask tokenfillask rpcs.

Player Activity

Create player object for yourself

User1 creates player1:

./komodo-cli -ac_name=KOGSCHAIN kogscreateplayer some-player1-name some-desc '{}'

'some-player1-name' and 'some-desc' - player name and description
'{}' means empty json with no parameters
Again use sendrawtransaction call to send tx in hex to the chain.

User2 creates player2:

./komodo-cli -ac_name=KOGSCHAIN kogscreateplayer some-player2-name some-desc '{}'

(here and further sendrawtransaction call is omitted) Note: each call to create a player should be done on this player's node (However it is also possible to create several players on the same node with the same user key)

List of created player ids maybe obtained with this rpc:

./komodo-cli -ac_name=KOGSCHAIN kogsplayerlist

Advertise player

Each player advertises himself that he is ready to play:

./komodo-cli -ac_name=KOGSCHAIN kogsadvertiseplayer '{"playerid": "id", "opts" : [ "playforkeeps", "playforfun", "playforwages" ] }'

Players create containers and add kogs to them

Each player creates a empty container:

./komodo-cli -ac_name=KOGSCHAIN kogscreatecontainer c1 some-desc playerid

Each call returns txns in hex each (for sending to the chain with sendrawtransaction rpc). The first tx is the created container tx (sendrawtransaction call will return a txid which is the containerid).

Each player adds kogs to his container (the kogs number must be equal to the param in the gameconfig

./komodo-cli -ac_name=KOGSCHAIN kogsaddkogstocontainer containerid kogid1 kogid2 ...

A Player starts a game

Start a new game:

./komodo-cli -ac_name=KOGSCHAIN kogsstartgame gameconfigid player1 player2

The call returns the game tx in hex (to be sent to the chain).

Each player commits random values to the game (qty = 1 + number-of-turns2player-number, so if max-turns=2 and there are two players each player needs to commit 1+222=9 randoms): ./komodo-cli -ac_name=KOGSCHAIN kogscommitrandoms gameid 0 r1 r2 r3 r4 r5 r6 r7 r8 r9

After all have committed, each player reveals the committed randoms: ./komodo-cli -ac_name=KOGSCHAIN kogsrevealrandoms gameid 0 r1 r2 r3 r4 r5 r6 r7 r8 r9

Each player deposits a container with kogs (with quantity equal to the value in the gameconfig) and deposits a slammer to the game:

./komodo-cli -ac_name=KOGSCHAIN kogsdeposittoken gameid containerid1 slammerid

The returned tx in hex should be sent to the chain with sendrawtransaction rpc.

As both containers and slammers are deposited, it is allowed for the player, who created the game, to create the first baton to the player whose turn is the first.

./komodo-cli -ac_name=KOGSCHAIN kogscreatefirstbaton gameid

The current state of the game (which player turn is now, kogs in stack and won kogs) could be obtained with the call:

./komodo-cli -ac_name=KOGSCHAIN kogsobjectinfo gameid

Example kogsobjectinfo output for a gameid:

./komodo-cli -ac_name=KOGSCHAIN kogsobjectinfo 5284cc0543d584fb84a848bf517409d45c4b832f0784894f3890f2390889c6f7
{
  "result": "success",
  "objectType": "G",
  "version": "1",
  "nameId": "",
  "descriptionId": "",
  "originatorPubKey": "035d3b0f2e98cf0fba19f80880ec7c08d770c6cf04aa5639bc57130d5ac54874db",
  "gameinfo": {
    "finished" : "false",
    "KogsWonByPlayerId": [
    ],
    "KogsWonByPlayerIdTotals": [
    ],
    "PreviousTurn": "none",
    "PreviousPlayerId": "none",
    "NextTurn": "1",
    "NextPlayerId": "fdff2619073db3906c953a6bcc79720fbf1010db5239a482f37cd1353daa13a7",
    "KogsInStack": [
      "dde435ee374f7c6fd362221fa24f973b49296c2b86c9c1701936db00b1ea421b",
      "1187d95ab79fda073cbecc04112ee4a94dcbe8551ade78446d86279e3aa786c7"
    ]
  }
}

(note that this rpc returns info about any object by its id, not only for gameids)

Players Perform Slams in Turn

Player whose turn is now sends his slam data to the chain:

./komodo-cli -ac_name=KOGSCHAIN kogsslamdata gameid playerid '{"armheight":"15", "armstrength":"20"}'

(The returned tx in hex should be sent to the chain with sendrawtransaction rpc).
After this call the chain applies the slam data, flips the kogs in the stack and removes the flipped kogs from the stack The chain also creates a baton for the next player passing the next turn to him. Then he calls kogsslamdata rpc too. After configured max-turns param the current slam finishes the game and the deposited containers and slammers are returned to the players (this is the currently implemented Play for keeps game mode).

The current version limitations

Limitations of the current kogs blockchain module version:

  • only play-for-fun mode is supported (no play-for-keeps and play-for-wages modes support yet)
  • bundles (with slammers) are not supported yet, slammers could be sent to a user by tokentransfer or traded by tokenask/tokenfillask rpcs.
Clone this wiki locally