# Overview Catheon Gaming's software development kit (referred to henceforth as CGC SDK) enables publishers to interface with CGC’s Core API, in order to integrate blockchain features into their apps. Through CGC integration, publishers will be able to get access to all on-chain data without having to directly integrate with the blockchain, allowing easy conversion to a web3 gaming model. In order to integrate with CGC, Catheon can also assist with NFT Minting, Token Minting, creating token exchange dashboards, NFT linking dashboards and a game testing simulator. ## Supported Blockchains CGC SDK currently supports the following blockchain networks: * Polygon * Binance Smart Chain * Ethereum * Solana If you would like to launch your game on a blockchain network that is not listed above, then [please get in touch](mailto:dev@catheongaming.com). ## Supported Languages The SDKs will be available in the following languages and should allow for seamless integration into any app: * C# * TypeScript * Java If you would like an implementation of the SDK in a language that is not listed above, then [please get in touch](mailto:dev@catheongaming.com). # Getting Started In this section, we will highlight what is required prior to integrating your game with CGC SDK. Please ask your Catheon appointed project lead to get in touch with us at with the information. Once we have approved the content provided, we will respond with next steps. If we need any further details, we will respond and ask for what is necessary. Please allow 1-3 days for a response. ## Metadata Requirements In order for your game to be added to the Catheon Gaming Center platform, the following details about your title need to be provided. All details are mandatory unless otherwise stated.
PropertyDescriptionExample
nameTitle of the gameSolChicks
descriptionBrief description of the gameSolChicks is an NFT-based battle-royale style virtual game, where users can earn cryptocurrency by playing.
splash_src_urlHigh-quality splash image of the game, no watermarks or logo should be presenthttps://media.catheongaming.com/solchicks/splash.jpg
logo_src_urlHigh-quality logo of the game title, must be in transparent and sent in *.PNG formathttps://media.catheongaming.com/solchicks/logo.png
developerThe name of the company developing the game0xPlay
website_urlWebsite URL https://www.solchicks.io/
discord_urlDiscord URL - optionalhttps://discord.gg/solchicks
telegram_urlTelegram URL - optionalhttps://t.me/solchicksnft
twitter_urlTwitter URL - optionalhttps://twitter.com/SolChicksNFT
statusCurrent state of game developmentDevelopment
long_descriptionExtended description of the gameSolChicks is a leading high-quality NFT-powered fantasy-playing game built on the Solana blockchain. The team builds games around adorable SolChick NFT collectibles, where players use their SolChicks as their characters in a unique gaming metaverse. Players can collect, breed, and raise one of the cute yet fierce SolChicks landing on Solana. Players have to defend against the enemy, SolFox and help the SolChick species continue on. SolChicks’ vision is to be the fastest-growing play-to-earn game built on the Solana blockchain with real entertainment value. Our mission is to build the next-generation MMORPG/MOBA game with real and proven entertainment value and bring it to the mass market. With the quality of our team and the evidence of our ability to scale quickly, SolChicks is the best positioned company to be the #1 dominant P2E player in the next 12 months.
genreGenre of the gameBattle Royale
tagsDescriptive tags associated with the game$SHARDS, NFT, PC, mobile, solana, p2e
## NFT Requirements In addition to the above, you will need to provide the following: * What chain you plan on releasing your NFTs on * What utility you plan on exposing through your NFTs * Sample metadata pertaining to your NFTs
ItemDetailsExample
Target ChainThe chain you plan on releasing your NFT collection onSolana
ImageSample image associated with the NFT collectionhttps://storage.googleapis.com/fractal-launchpad-public-assets/angrymals/assets/225.png
MetadataSample metadata associated with your NFT collectionhttps://storage.googleapis.com/fractal-launchpad-public-assets/angrymals/assets/225.json
TypeNFT collection category - e.g. PFP, lootbox or game passPFP
Proposed UtilityDescribe the added benefit of having the NFT collection in your game's ecosystemChaos Orbs are the core currency for Angrymals. It will be scarce (fixed supply) and tradable on the the blockchain. Chaos Orbs will be represented in the game by Chaos Shards, an in-game currency that can be converted to Chaos Orbs by owning an NFT.

To convert the in-game currency to the on-chain utility and governance token, the player needs to link an NFT to the game. Subsequently, the rarity of the linked NFT affects the conversion rate between the in-game currency and on-chain token.
## In-App Currency Requirements It is recommended that your game's economy blend elements of both traditional in-app purchase (IAP) and play-and-earn economies, such that traditional gamers will be able to enjoy the game without the blockchain, whilst crypto-savvy gamers are able to play the game for fun and earn tokens at the same time. The following in-app currency details need to be provided as part of onboarding:
ItemDetailsExample
NameThe name of the in-app currencyChaos Shards
SymbolThe symbol of the in-app currency is broadly equivalent to a crypto ticker, and although it has no restriction on its size it is usually 4-6 characters in lengthSHARDS
Initial supplyThe initial supply of the in-app currency10,000
LogoHigh-quality logo of the in app currency, must be in transparent and sent in *.PNG formathttps://media.catheongaming.com/shared/angrymals-shards.png
## On-Chain Token Requirements The following on-chain token details need to be provided as part of onboarding: | Item | Details | Example | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------- | | Name | The name of the on-chain token | Chaos Orbs | | Symbol | The symbol of the on-chain currency is broadly equivalent to a stock ticker, and although it has no restriction on its size it is usually 4-6 characters in length | ORBS | | Supply | The max supply of the on-chain token | 1,000,000,000 | | Logo | High-quality logo of the in app currency, must be in transparent and sent in \*.PNG format | | | Exchange Rate | A overview of exchange rate between the in-app currency and on-chain tokens - this can be determined by the NFT which the user owns or be some arbitrary value | 12% | | Target Chain | The chain you plan on releasing your NFT collection on | Polygon | # Integration Timeline On this page, you will find a high-level step-by-step overview of the standard SDK integration process from initial preparation to final in-game implementation.
StepWorkstreamDescription
1NFT Mint on Testnet

Once the sample collection of graphics and metadata have been produced, a sample collection of NFTs are minted on target chain's testnet.

Please note that these are just mock assets for the purpose of testing integration with the game.

2Token Mint on TestnetOnce details about the in-game currency and on-chain token have been produced, a small population of tokens are minted on the target chain's net.

Please note that these are just mock assets for the purpose of testing integration with the game.
3Token Exchange Dashboard Deployment

To facilitate in-game/on-chain token exchanges, a generic token exchange dashboard web app is created on the game's subdomain.

The token exchange dashboard allows the users to make a deposit (convert on-chain tokens into in-app tokens) and make a withdrawal (convert in-app tokens into on-chain tokens).

4NFT Link Dashboard DeploymentTo facilitate linking the NFT to the game, a generic NFT link dashboard web app is created on the game's subdomain.
5Game Simulator Testing

Once step 3 and 4 have been successfully deployed, publishers are given access to a game simulator which they can use to test the Token Exchange and NFT Link dashboard prior to integrating the SDK with the game.

At this stage, any issues noted with the token and NFT integration can be raised to Catheon Gaming.

6SDK IntegrationThe Game Simulator Testing in step 5 serves as the starting block for in-game integration.

Publishers are provided full access to the SDK and a dedicated Catheon Gaming developer to assist them with the integration. The publisher gets to control and decide how to use the SDK and Catheon will ensure that any on-chain activity required for the game development can be accessed through the SDK integration.
# Token Exchange Our token exchange dashboard allows the users to perform make a deposit (convert on-chain tokens into in-app tokens) and make a withdrawal (convert in-app tokens into on-chain tokens). ## Overview Each publisher is provided with access to a token exchange dashboard wherein authenticated users can perform token deposits (convert on-chain tokens into in-app tokens) or withdrawals (convert in-app tokens into on-chain tokens). Note that this dashboard is a template, we can re-design accordingly to match the publisher's website.
1. This panel shows you the list of NFTs that are currently in your wallet, along with its XR (exchange rate). NFT’s can have a XR value based on their rarity. An NFT with a higher XR gives the user a better conversion rate between in-game to on-chain token conversion 2. This panel shows you with a summary of the deposit and withdrawal transaction 3. This panel shows you your current in-game and on-chain currency 4. This panel allows you to switch between two transaction modes: deposit and withdrawal 5. This is an input box wherein you can enter the amount of tokens you want to deposit or withdraw 6. This panel shows you the amount of tokens that you will receive after an exchange 7. This panel shows your token exchange history ## Deposit When you make a deposit, you convert on-chain tokens into in-game tokens. The following applies: * The default exchange rate is 1 (100%). For example, if a user deposits 1000 on-chain tokens, the user will receive 1000 in-game tokens * There is no limit when depositing - a user can exchange as many on-chain tokens as they need for in-game tokens ## Withdrawal When you make a withdrawal, you convert in-game tokens into on-chain tokens. The following applies: * There are two types of exchange rates that can be applied: * The first is a fixed rate that does not depend on the NFT equipped at the time of conversion * The second is a variable rate that depends on the rarity of NFT equipped at the time of conversion * For example, let's say that the exchange rate is 25% and a user does not equip a NFT at the time of conversion * When the user attempts to withdraw 1000 in-game tokens, then they will only receive 750 on-chain tokens * However, if the user equips an NFT and the NFT rarity’s rate is 10, then when attempts to withdraw 1000 in-game tokens, then they will receive 900 on-chain tokens * It is possible to make it mandatory/optional for users to equip an NFT when withdrawing in-app tokens * Daily, weekly and monthly withdrawal limits can be set to preserve the integrity of your token ecosystem * This can apply to NFTs being used in withdrawals too ## Summary * When a user makes a deposit, our backend sends a deposit confirmation notification to the game, only if the user succeeds in executing the transaction using our smart contract * When a user makes a withdrawal, the exchange can only be made if the user’s in-game token balance is sufficient * The withdrawal will only commence once a notification has been received from the game that the in-game token balance has been reduced according to the withdrawal request * If a transaction fails due to issues related to network connectivity, a notification will be sent to the game to reimburse the user’s in-game tokens * All pending token exchanges are executed one at a time in sequential order # NFT Link Our NFT link dashboard allows users to link their NFTs to the game or unlink their NFTs from a game. ## Overview Each publisher is provided with access to a NFT link dashboard wherein authenticated users can link or unlink their NFTs from a game. Each link or unlink event sends a notification event to the game. From there, the game can update state accordingly by adding or removing privileges to the affected user. Note that this dashboard is a template, we can re-design accordingly to match the publisher's website.
1. This panel shows the currently unlinked NFTs which are in the user's wallet. 2. Once the user selects an unlinked NFT, then this panel appears - once the user clicks the “Link NFT” button, the NFT link operation will start. 3. This panel displays the currently linked NFTs which are in the custodial contract. The user also has the option to unlink the NFT from the custodial contract. ## Link During the link process, the NFT is moved from the user's wallet and put into a secure custodial contract. This is done to prevent the user moving the NFT between different wallets and gaining an unfair advantage. ## Unlink During the unlink process, the NFT is moved from the custodial contract and put back into the user's wallet. # Client Authorization The SDK exposes a limited set of in-game functionality to the user. If an activity requires a signed wallet transaction, then it has to happen through a browser dashboard. Every action performed by the SDK is attributed to a specific game and/or user. Both are identified by the parameters passed in the OAuth authorization header. It is important therefore that: * The user has permissions for what they are trying to achieve with their calls. * The user is active as no calls can be made from a non-existent/disabled/deleted user. After completing the steps in the [Getting Started](/getting-started) section, you will receive a CLIENT ID and CLIENT SECRET key pair. Each game needs these to access CGC's API. Once these key pairs have granted, each game will be able to construct a authorization header to meet our OAuth protocol requirements. ```typescript const cgcSdk = new CatheonGamingSdk( "773124bb-57cf-4eae-a7be-980c76ccd340", // client id "1qaz2wsx", // client secret true // dev mode enabled ); ``` ## Access Token Management {% hint style="info" %} Please note that the following methods are automatically handled when you instantiate a new CatheonGamingSDK object, so you do not need to worry about them. We have listed them below for informational purposes only. {% endhint %} ### RequestAccessToken If clientId and clientSecret are provided correctly, you can request an access token from the CGC API. This is required to identify your game against our services for security purposes. ```typescript const cgcTokenResponse = await cgcSdk.requestAccessToken(); ``` **Response:** ``` Event: { string access_token, int64 expiry_access_date, string refresh_token, string token_type } ``` ### RenewAccessToken After receiving your token, you can request that it be renewed. ```typescript const cgcTokenResponse = await cgcSdk.renewAccessToken() ``` **Params:** `string refreshToken` **Response:** ``` Event: { string access_token, int64 expiry_access_date, string refresh_token, string token_type } ``` ### RevokeAccessToken After receiving your token, you can request that it be revoked. ```typescript const cgcTokenResponse = await cgcSdk.revokeAccessToken() ``` **Response:** ``` Event: { string status, int statusCode, string message, } ``` # Notification Events The SDK is notification based, so from within your game, you will need to have a clean way of responding to each with complementary events. This is to prevent games needing to continuously poll our backend for updates. The SDK is focused around providing data streams for two assets - NFTs and tokens. ## Game Actions ### BalanceRequested When a request is made for the user's balance, a BalanceRequested event is triggered. The handler for this event should respond with balance for the user by using the function `SendBalance(receivedEvent, balance)`. The RequestId stored in event will be used for request identification on API-side. ``` Event: { string UserEmail, string RequestId } ``` This is an example of the notification that will be sent to the game: ```json { event: 'BalanceRequested', requestId: '26ebb6e3-48f8-46d5-b930-a302368f0701', email: 'user@test.com' } ``` ### InGameCurrencyDeposit When the user has exchanged on-chain tokens into in-app currency, the game receives a notification with amount deposited for the current user. It is up to the game to update the user's in-game currency with the amount provided. The game will need to increment the user's in-game currency by this amount. ``` Event: { string UserEmail, double BalanceIncrease, string TxHash } ``` This is an example of the notification that will be sent to the game: ```json { event: 'InGameCurrencyDeposit', requestId: '00077f08-26b4-4f95-a1ac-9ba914982273', email: 'test@catheongaming.com', balanceIncrease: 555, txHash: '0xc13d7905be5c989378a945487cd2a1193627ae606009e28e296d48ddaec66162' } ``` ### NftLinkStatusChanged When the user links or unlinks an NFT to the game, an NftLinkStatusChanged event is triggered. ``` Event: { string user_email, string wallet_address, string token_address, int status, string metadata } ``` This is an example of the notification that will be sent to the game: ```json { user_email: 'w54661c@gmail.com', wallet_address: '0xB05D9f248cCf546fE9d52A9ADA340cc361c8c163', token_address: '0x086cce368ee810f77257479b90bed1bb164420b5_176', status: 0, metadata: '{"metadata":{"name":"Runt the Wolf #4664","image":"https://storage.googleapis.com/fractal-launchpad-public-assets/angrymals/assets/4372.png","attributes":[{"value":"Runt","trait_type":"Angrymal"},{"value":"Wolves","trait_type":"Race"},{"value":"Common","trait_type":"Rarity"},{"value":"Brain dome","trait_type":"Hat"},{"value":"None","trait_type":"Eyes"},{"value":"None","trait_type":"Mouth"},{"value":"None","trait_type":"Makeup"},{"value":"None","trait_type":"Ears"},{"value":"Chinese dress","trait_type":"Dress"}],"description":"Show off your support with wacky in-game player banners that enables the core play-to-earn functionality, unlocks exclusive features, events and additional bonuses"},"collection":{"name":"Genesis Player Banner","symbol":"Angrymals"}}' } ``` ### InGameCurrencyWithdrawal This event will be sent to the game when the user starts to exchange in-game currency for on-chain tokens. The handler for this event should adjust the user balance and respond with a `Result` by using the function `SendWithdrawResult(receivedEvent, result)`. For details on how the token withdrawal works, please have a look at this [call diagram](https://hackmd.io/g5c7eXtnRAW5aaprgvtnfg?view). ``` Event: { string RequestId, string UserEmail, double BalanceDecrease } ``` This is an example of the notification that will be sent to the game: ```json { event: 'InGameCurrencyWithdrawal', requestId: '9ad3e825-ba65-4b0a-b03b-8f4e39cf1fd3', email: 'test@catheongaming.com', balanceDecrease: 555 } ``` ### RollbackWithdrawal This event will be sent to the game when an on-chain transaction fails. The handler for this event should adjust user balance and respond with `Result` by using the function `SendRollbackWithdrawResult(receivedEvent, result)`. ``` Event: { string RequestId, string UserEmail, double BalanceIncrease, string TxHash } ``` This is an example of the notification that will be sent to the game: ```json { event: 'RollbackWithdrawal', requestId: 'e95a9342-3c06-4223-83b3-0428bb89f524', email: 'test@catheongaming.com', balanceIncrease: 555, txHash: '0xc13d7905be5c989378a945487cd2a1193627ae606009e28e296d48ddaec66162' } ``` # User Accounts To make use of any SDK functionality, a player must have a CGC account. CGC accounts are for users to connect in-game IDs with their NFTs, as well as being able to aggregate their NFTs across chains. It is fairly straightforward to implement this as part of your login and registration flow. ## AuthorizeUser **Params:** `string email, string password` \ **Response:** `string result` or throw exception in case of error ``` var result = cgc.AuthorizeUser("user@domain.com", "123"); ``` ## Catheon Connect {% hint style="info" %} Due to this approach (i.e. email and password requirement), we cannot accept social login (Facebook, Gmail, Twitter) or usernames. {% endhint %} In the case of a game that does not support email and password login, we would suggest that they implement a Catheon Connect button in their game which would invoke the same method but request a password from the user (post-login) or a one-time prompt to request the user enter their password. ![](https://lh4.googleusercontent.com/HKbvsaUyQ8cpsO0GNdY8VHLov_RQ_XHOFxdBg3lLjE3du1rzn8chUKeAAnQbpTi9E7EIfNSTQ_Y8V6hp-1z1vLl8Zmv6f8oLkP1spjkbvvIet6jyld394eOFFjbuWBl2lWuIn2yWanAx762nJe94PV3CS46ZOyPQtdYMN5Eqj8w3xOGL9O9Q4HCC) This button would invoke a in-game modal window similar to the below, wherein the user’s email address is prefilled, and they are asked to input their password. ![](https://lh6.googleusercontent.com/L8hHGHj94MACS2D5x4P6nHla_oebhz_MuWQ4r8Dq1x044vY91u_nkSz4Qba3ARpgT3VTDyQq4ZkJxi9yjcTp_QtV3yz79VtM5GqIwnhfHVkrSuVJCwBn5Mi-tD7ZdnYLngLVYPAZ5AEthSN5o9L2o2qcse_liwXQzgSxR4secFth5xiYafy058G7)