From ce446575b8edccad1f0b28ca12e0b75860185c31 Mon Sep 17 00:00:00 2001 From: Robby Uitbeijerse Date: Wed, 15 Nov 2023 15:59:24 +0100 Subject: [PATCH] chore: improved game documentation (#103) --- pages/service/_meta.json | 2 +- pages/service/game/_meta.json | 6 ++ pages/service/game/api-keys.mdx | 51 ++++++++++++ pages/service/game/introduction.mdx | 44 +++++++++++ pages/service/game/managing-contracts.mdx | 92 ++++++++++++++++++++++ pages/service/game/updating-game.mdx | 28 +++++++ pages/service/marketplace/introduction.mdx | 2 +- pages/service/your-game.mdx | 51 ------------ 8 files changed, 223 insertions(+), 53 deletions(-) create mode 100644 pages/service/game/_meta.json create mode 100644 pages/service/game/api-keys.mdx create mode 100644 pages/service/game/introduction.mdx create mode 100644 pages/service/game/managing-contracts.mdx create mode 100644 pages/service/game/updating-game.mdx delete mode 100644 pages/service/your-game.mdx diff --git a/pages/service/_meta.json b/pages/service/_meta.json index fd42789..7c6b8ca 100644 --- a/pages/service/_meta.json +++ b/pages/service/_meta.json @@ -4,7 +4,7 @@ "type": "separator", "title": "Guides" }, - "your-game": { + "game": { "title": "Your game" }, "profiles": { diff --git a/pages/service/game/_meta.json b/pages/service/game/_meta.json new file mode 100644 index 0000000..6a39013 --- /dev/null +++ b/pages/service/game/_meta.json @@ -0,0 +1,6 @@ +{ + "introduction": "Introduction", + "api-keys": "API keys", + "managing-contracts": "Managing contracts", + "updating-game": "Updating game" +} diff --git a/pages/service/game/api-keys.mdx b/pages/service/game/api-keys.mdx new file mode 100644 index 0000000..d93b440 --- /dev/null +++ b/pages/service/game/api-keys.mdx @@ -0,0 +1,51 @@ +# API keys + +When you've received your Beam accounts API key, you're received three different keys: + +- **a read-only key** - this key allows you use read-only endpoints +- **a read & write key** - this key allows you to read and manage data +- **a regenerate key** - this allows you to regenerate your api keys + +The **regenerate key** is reserved for one specific action - to invalidate, and re-create the API keys we provided to you. This could come in handy if you are looking to implement a rotating key solution where you would like to invalidate the API key being used in your backend every x hours/days. + +Note that, as soon as you regenerate the keys, your existing keys will be invalidated as soon as you retrieve your new keys. When you use the method, the response will contain a new set of three keys - store them securely! + +Below you'll find an example on how to regenerate your API keys. + +```typescript +import { Beam } from "@onbeam/node"; + +const beam = new Beam("x-regenerate-api-key"); + +const keys = beam.game.regenerateApiKeys(); + +// { +// "id": "string", +// "createdAt": "string", +// "updatedAt": "string", +// "name": "string", +// "description": "string", +// "coverImageUrl": "string", +// "logoImageUrl": "string", +// "chainIds": [ +// 0 +// ], +// "apiKeys": [ +// { +// "type": "ReadOnly", +// "createdAt": "string", +// "apiKey": "string", +// }, +// { +// "type": "ReadWrite", +// "createdAt": "string", +// "apiKey": "string", +// } +// { +// "type": "Regenerate", +// "createdAt": "string", +// "apiKey": "string", +// } +// ] +// } +``` diff --git a/pages/service/game/introduction.mdx b/pages/service/game/introduction.mdx new file mode 100644 index 0000000..c94ed26 --- /dev/null +++ b/pages/service/game/introduction.mdx @@ -0,0 +1,44 @@ +# Game + +Your game registration within Beam consists of information that is managed by Beam, and information manageable by you. When we register your api key, we'll also be in touch about the assets you want to register in your game. We can either provide contract templates for generic in-game currencies, but are also happy to help you with bridging over assets from one chain to another - be in touch! + +Here are some of the key pieces of info you'll need to get started with implementing with Beam: + +- [API keys](/service/game/api-keys): API keys and how to invalidate them + +- [Managing contracts](/service/game/managing-contracts): Add and remove asset contracts to your game + +- [Updating your game](/service/game-updating-game): Update information (name, visuals) of your game in the Beam Companion app + +--- + +## Retrieving your game + +If you're just interested in the currently resgistered information of your game in the Beam accounts API, simply call the `getGame` method. You'll find an example on how to do this below. + +**Note:** we don't expose your API keys in this request, as we don't want people to accidentally expose them in application logs. + +```typescript +import { Beam } from "@onbeam/node"; + +const beam = new Beam("x-api-key"); + +const game = await beam.game.getGame(); + +// { +// "id": "string", +// "name": "string", +// "contracts": [ +// { +// "type": "ERC20", +// ... +// } +// ], +// "policies": [ +// { +// "id": "string", +// ... +// } +// ] +// } +``` diff --git a/pages/service/game/managing-contracts.mdx b/pages/service/game/managing-contracts.mdx new file mode 100644 index 0000000..1b1434b --- /dev/null +++ b/pages/service/game/managing-contracts.mdx @@ -0,0 +1,92 @@ +## Managing contracts + +If you want to run transactions for profiles that interact with specific contracts, the contract address will need to be registered for your game. + +We provide a method for you to add any contract to your game, as long as you can provide us with the ABI and contract address. As adding a contract address to your game is probably a one time action that you won't repeat (a lot) over time, we can also recommend simply interacting with the hosted [Swagger UI](https://api.testnet.onbeam.com/api/game) to simply add the necessary contracts to you rgame. + +--- + +### Asset data + +At the moment of writing **you are (technically) required** to submit your asset contracts to Sphere in order for the SDK to be hydrated with data, since we use Sphere (our NFT marketplace) as the source for all asset related data. + +https://testnet.sphere.market/ + +--- + +### Companion app + +If you're using the [Beam Companion](/service/companion/introduction) app, it might be good to know that as soon as you add a contract to your game, all connected users to profiles of your game are able to see said contract in the [Beam Companion](/service/companion/introduction) app. + +--- + +### Adding a contract + +Adding a contract is as simple as calling the `addContractToGame` method. + +```typescript +import { Beam } from "@onbeam/node"; + +const beam = new Beam("x-api-key"); + +const contract = beam.game.addContractToGame({ + address: "string", // the deployed contract address + type: "ERC20", // ERC721, ERC1155 + chainId: 13337, // 13337 for Beam testnet + name: "string", // The name of the asset contract, for example: 'Card Packs' + + // the JSON abi for the contract, we recommend you grabbing it from the explorer if you have a deployed & verified contract + abi: [ + { + name: "string", + type: "string", + anonymous: true, + payable: true, + constant: true, + stateMutability: "string", + gas: "string", + inputs: [ + { + name: "string", + type: "string", + indexed: true, + internalType: "string", + components: ["string"], + }, + ], + outputs: ["string"], + }, + ], +}); + +// { +// "type": "ERC20", +// "id": "string", +// "createdAt": "string", +// "updatedAt": "string", +// "externalId": "string", +// "address": "string", +// "name": "string", +// "chainId": 0, +// "gameId": "string" +//} +``` + +### Deleting a contract + +Removing a contract from your game is just as simple, simply use the `removeContractFromGame` method to remove it. + +```typescript +import { Beam } from "@onbeam/node"; + +const beam = new Beam("x-api-key"); + +const contract = beam.game.removeContractFromGame({ + address: "string", // the deployed contract address + chainId: 13337, // 13337 for Beam testnet +}); + +// { +// "success": true +//} +``` diff --git a/pages/service/game/updating-game.mdx b/pages/service/game/updating-game.mdx new file mode 100644 index 0000000..4cb1102 --- /dev/null +++ b/pages/service/game/updating-game.mdx @@ -0,0 +1,28 @@ +## Updating your game + +Some of the fields for your game's registration are being used in the Beam companion app. You can update through the `updateGame` method that's available on any of our [SDK's](/service/sdk) or by directly communicating with our [RESTful API](/service/full-api-reference) + +--- + +### Companion app + +If you're using the [Beam Companion](/service/companion/introduction) app, it might be good to know that as soon as you change the name or visuals of your game, all connected users to profiles of your game are able to see these changes in the [Beam Companion](/service/companion/introduction) app. + +--- + +### Updating your game + +Updating your game is as simple as calling the `updateGame` method. + +```typescript +import { Beam } from "@onbeam/node"; + +const beam = new Beam("x-api-key"); + +await beam.game.updateGame({ + name: "Your game's name", + description: "Lorem ipsum dolor...", + coverImageUrl: "ipfs://..", + logoImageUrl: "ipfs://..", +}); +``` diff --git a/pages/service/marketplace/introduction.mdx b/pages/service/marketplace/introduction.mdx index 02a5c1f..698d1ff 100644 --- a/pages/service/marketplace/introduction.mdx +++ b/pages/service/marketplace/introduction.mdx @@ -9,7 +9,7 @@ import { Callout } from "nextra/components"; In order to get a marketplace going, we offer various methods that can help you get started with listing assets. Keep in mind that the marketplace itself is a pre-release product waiting to be released in Q4. -In order to create a full marketplace integration it is important to understand all of the possibilities that you have. +In order to create a full marketplace integration it is important to understand all of the possibilities that you have, here are some articles to get you started: - [Currencies](/service/marketplace/currencies): Supported currencies in Beam marketplace diff --git a/pages/service/your-game.mdx b/pages/service/your-game.mdx deleted file mode 100644 index f81f038..0000000 --- a/pages/service/your-game.mdx +++ /dev/null @@ -1,51 +0,0 @@ -# Game - -Your game registration within Beam consists of information that is managed by Beam, and information manageable by you. When we register your api key, we'll also be in touch about the assets you want to register in your game. We can either provide contract templates for generic in-game currencies, but are also happy to help you with bridging over assets from one chain to another - be in touch! - -The registered contracts and policies allow you to interact with profiles and assets in Beam. As of writing, we don't allow you to add more asset contracts to your game in Beam manually, as there are a couple of manual steps involved with ensuring the contract is not just added to your game, but also deployed correctly and indexed from the blockchain. To make this a bit more tangible: - -- You are able to manage fields like the name of your game, a description and a cover image (used within the Beam companion app) -- We will register / add your asset contracts and policies for your game based on your specific needs - -## Retrieving your game - -```typescript -import { Beam } from "@onbeam/node"; - -const beam = new Beam("x-api-key"); - -const game = await beam.game.getGame(); - -// { -// "id": "string", -// "name": "string", -// "contracts": [ -// { -// "type": "ERC20", -// ... -// } -// ], -// "policies": [ -// { -// "id": "string", -// ... -// } -// ] -// } -``` - -## Updating your game - -Some of the fields for your game's registration in Beam will be used in the upcoming Beam companion app. You can update through the `updateGame` method that's available on any of our [SDK's](/service/sdk) or by directly communicating with our [RESTful API](/service/full-api-reference) - -```typescript -import { Beam } from "@onbeam/node"; - -const beam = new Beam("x-api-key"); - -await beam.game.updateGame({ - name: "New name", - description: "Lorem ipsum dolor...", - coverImageUrl: "ipfs://..", -}); -```