API call order

The order of interaction with backend

Game Start

Here is the list in order of API to call when game is launched. This data is to be shown in the Levels page, not in the main menu.

1. Fetch Session Data (Smartcontract)

The Session data contains general information about how many levels the current season has, the grand reward type and so on. This API is containing two parts. First we get the latest Session ID:

zombieFarm.methods.lastSessionId().call()

It returns the session id for the current running season. Or for the latest closed season.

Once we have the session id, we can get the latest session data:

zombieFarm.methods.sessions(sessionId).call()

It returns the Session struct defined in the Game's smart contract.

For now, the Smart Contract is not ready, but we will put here the Struct, once the Smart Contract will be ready.

2. Fetch Level Parameters (Backend)

After fetching the Season (also called Session), we show the first level. Each level will have three staking options. The options are different for each player. So let's get the first level information from the API backend:

Get Level Options for the player

GET https://api.seascape.network/zombie-farm/get-level-options/:session_id/:level_id/:wallet_address

Return the options to show for the user.

Path Parameters

Name	Type	Description
wallet_address	string	The Wallet address of the user. It should start with 0x prefix.
level_id	integer	Level ID
session_id	integer	Season ID

200 Return list of options in JSON format. It returns an array of objects. Where each object indicates the option parameters. The Object has the following common values. The parameters will be always in the Response from the server: category - the possible options could be find on Option categories. The option category determines the staking tokens and earning tokens. duration - how long user has to stake. Its in seconds. The option is cosidered to be completed, only if a user stakes for duration time. rewardPool - total amount of Tokens to distribute to stakers. Its in decimal format. optionId - the Unique identifier of the option playerParams - the staking parameters of the user in the option. The value of the parameter depends on the The following parameters are included depending on category parameter: singleTokenParams - contains the staking and earning asset infomation for "single-token" option category type. If the category of option is different, then this parameter won't be included. Instead another parameter will be added from Backend server.

[
   {
      "category":"single-token",
      "duration":25200,
      "stakeAmount": 200,
      "optionId":1,
      "playerParams":{
         "claimed":2.12,
         "stakeTime":0,
         "staked":0,
         "stakedDuration":23,
         "withdrawn":0
      },
      "rewardPool":2000,
      "singleTokenParams":{
         "earnToken":{
            "address":"0x3b00ef435fa4fcff5c209a37d1f3dcff37c705ad",
            "icon":"https://icons.iconarchive.com/icons/cjdowner/cryptocurrency-flat/1024/Tether-USDT-icon.png",
            "name":"USD Tether",
            "symbol":"USDT"
         },
         "maxDeposit":10000,
         "minDeposit":10,
         "stakeToken":{
            "address":"0x168840Df293413A930d3D40baB6e1Cd8F406719D",
            "icon":"https://s2.coinmarketcap.com/static/img/coins/200x200/8365.png",
            "name":"Crowns",
            "symbol":"CWS"
         }
      }
   },
   {
      "category":"single-token",
      "duration":25200,
      "stakeAmount": 200,
      "optionId":2,
      "playerParams":{
         "claimed":2.12,
         "stakeTime":0,
         "staked":0,
         "stakedDuration":23,
         "withdrawn":0
      },
      "rewardPool":2000,
      "singleTokenParams":{
         "earnToken":{
            "address":"0x168840Df293413A930d3D40baB6e1Cd8F406719D",
            "icon":"https://s2.coinmarketcap.com/static/img/coins/200x200/8365.png",
            "name":"Crowns",
            "symbol":"CWS"
         },
         "maxDeposit":10000,
         "minDeposit":10,
         "stakeToken":{
            "address":"0x3b00ef435fa4fcff5c209a37d1f3dcff37c705ad",
            "icon":"https://icons.iconarchive.com/icons/cjdowner/cryptocurrency-flat/1024/Tether-USDT-icon.png",
            "name":"USD Tether",
            "symbol":"USDT"
         }
      }
   },
   {
      "category":"single-token",
      "duration":25200,
      "stakeAmount": 200,
      "optionId":3,
      "playerParams":{
         "claimed":2.12,
         "stakeTime":0,
         "staked":0,
         "stakedDuration":23,
         "withdrawn":0
      },
      "rewardPool":2000,
      "singleTokenParams":{
         "earnToken":{
            "address":"0x3b00ef435fa4fcff5c209a37d1f3dcff37c705ad",
            "icon":"https://icons.iconarchive.com/icons/cjdowner/cryptocurrency-flat/1024/Tether-USDT-icon.png",
            "name":"USD Tether",
            "symbol":"USDT"
         },
         "maxDeposit":10000,
         "minDeposit":10,
         "stakeToken":{
            "address":"0x168840Df293413A930d3D40baB6e1Cd8F406719D",
            "icon":"https://s2.coinmarketcap.com/static/img/coins/200x200/8365.png",
            "name":"Crowns",
            "symbol":"CWS"
         }
      }
   }
]

For more information about structure of singleTokenParams, or to know more about the names and the structures of staking/earning parameters of another option category, please visit Option categories

3. Create instance of contracts for each Challenge.

Once we get the challenge data, we need to create the Contract Instance of them in our game. The contract instances are used later.

For creating the contract instance we need two parameters. The first is contract address. The second is ABI interface.

Getting the address

Call the backend method:

window.zombieFarm.methods.supportedChallenges(optionId).call()

The parameters of supportedChallenges are:

optionId - The challenge (aka option) id that we received from the backend, when we fetched level data.

Getting the ABI

Copy the ABI from the github repo in the game.

seascape-smartcontracts/abi at game-5 · blocklords/seascape-smartcontractsGitHub

And assign each abi to option category. For example for "single-token" option category, use SingleTokenChallenge.json fetched from github.

Finally once we know how to get ABI and address of the option, we need to create Contract instances and assign to each challenge (aka option) id:

// for each challenge returned from the backend
for (var i=0; i<3; i++) {
    let optionId = backendResponse[i].optionId;
    
    // Get from the Zombie Farm contract
    let challengeAddress = "";
    
    // Get from game by backendResponse[i].category
    let challengeAbi = "";
    
    cc.challenges[optionId] = new web3.Contract(challengeAddress, challengeAbi);
}

4. Create instances of staking tokens.

For each challenge, we need to create an instance of staking token. For Single Token category challenges, the staking token instance is created as like this:

let stake = backendResponse[i].singleTokenParams.stakeToken.address;
let abi = cc.blockchainConfig.crowns_abi

cc.stakes[optionId] = new web3.Contract(stake, abi);

Repick

In order to decide to show the "Repick" button on the challenge card or not visit the Challenge card page.

Here is the steps to reproduce the "Repick" button.

1. Open the popup about Repick fee.

The Repick fee is in Crowns, and is available at window.session.repickFee. Since the repick fee is in Wei, we need to show to user in float format: web3.utils.fromWei(window.session.repickFee)

In Cocos Creator framework, the window.session will be available as cc.session.

2. Send transaction to Zombie Farm contract

Once the player gets confirmation about repick fee, he clicks on "send" button on popup. The click will send a transaction to the zombie farm contract by calling

window.zombieFarm.methods.repick(sessionId, challengeId).send()

The parameters passed to repick method: sessionId - The current game season. challengeId - The current challenge that user wants to replace.

3. Return player option data from server.

Just like at Game Start, Fetch the level parameters

https://api.seascape.network/zombie-farm/get-level-options/:sesionid/:level_id/:wallet_address

Boost

In order to decide to show the "Boost" button on the challenge card or not visit the Challenge card page.

Here is the steps to reproduce the "Repick" button.

1. Open the popup about Boost fee.

The Boost fee is in Crowns, and is available at window.session.speedUpFee. Since the repick fee is in Wei, we need to show to user in float format: web3.utils.fromWei(window.session.speedUpFee)

In Cocos Creator framework, the window.session will be available as cc.session.

2. Send transaction to Zombie Farm contract

Once the player gets confirmation about repick fee, he clicks on "send" button on popup. The click will send a transaction to the zombie farm contract by calling

window.zombieFarm.methods.speedUp(sessionId, challengeId).send()

The parameters passed to speedUpmethod: sessionId - The current game season. challengeId - The current challenge that user wants to speed up.

3. Update the Challenge card.

If transaction went successfully, update the card, including the timer to completed stage.

Stake

First we approve user's staking token to use his tokens in Zombie Farm.

We do it by calling:

let approveAmount = web3.utils.toWei("1000000", "ether");
window.stakes[challengeId].methods.approve(ZombieFarm._address, approveAmount ).send();

The staking parameters that are sent to smart contract calls the method:

window.zombieFarm.methods.stake(sessionId, challengeId, data).send()

The arguments of stake method:

sessionId - The current active game season.

challengeId - The challenge for which user wants to stake.

data - the byte parameter of the challenge about staking tokens. It is different for each option category. So please look at option categories page.

Unstake

The unstaking parameters that are sent to smart contract calls the method:

window.zombieFarm.methods.unstake(sessionId, challengeId, data).send()

The arguments of unstake method:

sessionId - The current active game season.

challengeId - The challenge for which user wants to stake.

data - the byte parameter of the challenge about unstaking tokens. It is different for each option category. So please look at option categories page.

Claim

User claims the tokens that farmed by staking token. It is done by calling the method:

window.zombieFarm.methods.claim(sessionId, challengeId).send()

The arguments of claimmethod:

sessionId - The current active game season.

challengeId - The challenge for which user wants to stake.

Once its check the value of logs for earned tokens.