diff --git a/.gitignore b/.gitignore index d78cb85..154dbb5 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,5 @@ node_modules .vercel .env + +.idea \ No newline at end of file diff --git a/README.md b/README.md index 940dfd6..a122e77 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ If you would like to get your hands dirty without reading our documentation, we ## Getting started ```typescript -import { Beam } from "@onbeam/node"; +import { Beam } from "@onbeam/automation-api-client"; const beam = new Beam("x-api-key"); @@ -50,7 +50,7 @@ In this example, we initialize an instance of Beam by passing your api key. We t Profiles are managed by you, and through your api key you are able to transfer / trade and manage assets of the profiles of your users ```typescript -import { Beam } from "@onbeam/node"; +import { Beam } from "@onbeam/automation-api-client"; const beam = new Beam("x-api-key"); diff --git a/pages/service/_meta.json b/pages/service/_meta.json index c9c039b..203ef0a 100644 --- a/pages/service/_meta.json +++ b/pages/service/_meta.json @@ -1,11 +1,24 @@ { + "--- Beam": { + "type": "separator", + "title": "Beam" + }, "index": "Getting started", - "--- Self-custody (Beta)": { + "managed-or-self-custody": { + "title": "Player or Automation API" + }, + "game": { + "title": "Managing your game" + }, + "--- Player API (Beta)": { "type": "separator", - "title": "Self-custody (beta)" + "title": "Player API (beta)" }, - "self-custody": { - "title": "Getting started" + "introduction-self-custody": { + "title": "Introduction" + }, + "implementation-self-custody": { + "title": "Implementation" }, "operations": { "title": "Operations (beta)" @@ -13,39 +26,33 @@ "sessions": { "title": "Sessions (beta)" }, - "--- Guides": { - "type": "separator", - "title": "Guides" - }, - "game": { - "title": "Managing your game" - }, - "profiles": { - "title": "Profiles" - }, "transactions": { "title": "Transactions" }, - "policies": { - "title": "Policies" - }, "assets": { "title": "Assets" }, - "trading": { - "title": "Trading" - }, "marketplace": { "title": "Marketplace" }, "exchange": { "title": "Exchange" }, - "companion": { - "title": "Companion" + "--- Automation API": { + "type": "separator", + "title": "Automation API" }, - "sphere": { - "title": "Sphere" + "introduction-managed": { + "title": "Introduction" + }, + "profiles": { + "title": "Profiles" + }, + "policies": { + "title": "Policies" + }, + "trading": { + "title": "Trading" }, "reporting": { "title": "Reporting" @@ -59,13 +66,20 @@ }, "environments": "", "full-api-reference": "", + "--- Ecosystem": { + "type": "separator", + "title": "Ecosystem" + }, + "sphere": { + "title": "Sphere" + }, + "companion": { + "title": "Companion" + }, "--- More": { "type": "separator", "title": "More" }, - "roadmap": { - "title": "Roadmap" - }, "terms-of-service": { "title": "Terms of Service" }, diff --git a/pages/service/assets/introduction.mdx b/pages/service/assets/introduction.mdx index 09b9f9b..dadd414 100644 --- a/pages/service/assets/introduction.mdx +++ b/pages/service/assets/introduction.mdx @@ -10,11 +10,6 @@ Asset management is a crucial part of the Beam integration within your game. Dep By providing these options through the sdk, you are able to create a frictionless in-game marketplace built on beam without having to worry about creating infrastructure to support it. -### Roadmap - -Throughout the coming months, we'll be releasing additional features that will help you to provide a more complete marketplace experience, with features ranging from programmatic offers, auctions and extensive filtering options to allow you to create a full-fledged in-game marketplace solely by relying on the Beam marketplace. - - Feel like something is missing, and needs to be prioritized? Check out our - [2024 roadmap](/service/roadmap) or let's have a chat through build@onbeam.com + Feel like something is missing, and needs to be prioritized? Let's have a chat through build@onbeam.com! diff --git a/pages/service/companion.mdx b/pages/service/companion.mdx new file mode 100644 index 0000000..79cd821 --- /dev/null +++ b/pages/service/companion.mdx @@ -0,0 +1,35 @@ +--- +title: Introduction to Beam Companion +--- + +import { Callout, Cards, Card } from "nextra/components"; + +# Introduction to Beam Companion + +The Beam Companion app allows users to manage and access their on-chain NFTs earned through playing your game. + +You'll be able to find the latest version of the Beam Companion through the following links + + + + + + + + Make sure you connect to **Beam testnet** in order to implement the application + during your development process. You can switch to testnet by switching on the + log-in screen of the app. + + +### Connecting users to the Beam Companion app + +The Beam Companion app works based on the same authentication solution as is being used in the self-custody features of Beam, meaning that any user you onboard through that solution will automatically be linked to your game and is able to use the Beam Companion app. + diff --git a/pages/service/companion/_meta.json b/pages/service/companion/_meta.json deleted file mode 100644 index 9d87677..0000000 --- a/pages/service/companion/_meta.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "introduction": "Introduction", - "connecting-your-users": "Connecting your users", - "verifying-webhooks": "Verifying webhooks" -} diff --git a/pages/service/companion/connecting-your-users.mdx b/pages/service/companion/connecting-your-users.mdx deleted file mode 100644 index 5bbc223..0000000 --- a/pages/service/companion/connecting-your-users.mdx +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Connecting your users ---- - -## Connecting your users to the Beam Companion - -What is important to understand is that the Profiles entity within Beam is not exclusively a matter of players. Profiles could be used for various purposes, one of which is [match profiles](/service/profiles/match-profiles). - -However - in our opinion - it makes a ton of sense to create a Profile for each of your players as soon as you want something to happen on-chain. You can use these player profiles to manage a user and their assets. On-chain tokens they earned (or bought), NFTs they minted (or you minted on their behalf) all can be sent to the player profile for each player. - -In order to allow players to see and manage their assets outside of your game, we offer a way to link-up their profile to an SSO authenticated user identity. While it's not required, the companion app offers an extension of the web3 experience where users are able to manage, give away and trade assets, without you having to facilitate this. - -### Connection request - -If you want to allow players to control their assets outside of your game, providing them the web3 experience, you would need to create a connection request for a profile. - -```typescript -const request = await beam.profiles.createConnectionRequest("profile-id", { - callbackUrl: - "https://your-games-backend.your-game.com/api/incoming-webhook/:profile-id", -}); - -// { -// "id": "string", -// "challenge": "c5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470", -// "validUntil": "2023-08-30T08:35:08+00:00" -// } -``` - -The `challenge` property that we send you when you created this Connection request is essentially a key meant solely for the player behind the profile you want to link up to a user within Beam. - -The next step is allowing the user to obtain the challenge we created within the app, as this challenge enables up to create the connection. - -#### QR code - -If your game is running on a console, PC, or in a browser, we suggest encoding the challenge in a QR code. The user can scan the QR code, which establishes a link between the user in Beam and the player profile you have registered. We suggest creating a QR code that includes the following information: - -```md filename="QR CODE" -https://account.onbeam.com/connection-request?challenge=c5d2... -``` - -This implementation guides users who do not have the app installed to the website where they can find links to download the app on their device. If users already have the app installed and scan the QR code using their native camera app, they will be directed to the companion app. Additionally, if users scan it from within the companion app, the connection request will also be handled correctly. - -#### Deeplink - -If your game is running on iOS or Android, you could pass the challenge down a deeplink that opens up the Beam companion app. This link is exactly the same as the one you use for the QR code: - -```md filename="DEEPLINK" -https://account.onbeam.com/connection-request?challenge=c5d2... -``` - -It'll produce the same result as the QR code setup we mentioned earlier. Users who don't have the companion app already installed will be directed to a website where they can easily find links to download the app on their device. If the user already has the companion app installed, it will open the app and handle the connection request. - -#### Webhook - -By providing a `callbackUrl` when creating a Connection request, we'll be able to provide you with an incoming webhook telling you that a profile was linked up to a user. diff --git a/pages/service/companion/introduction.mdx b/pages/service/companion/introduction.mdx deleted file mode 100644 index 98c3e3f..0000000 --- a/pages/service/companion/introduction.mdx +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Introduction to Beam Companion ---- - -import { Callout, Cards, Card } from "nextra/components"; - -# Introduction to Beam Companion - -We recently released the Beam Companion app. The app allows users to manage and access their on-chain NFTs earned through playing your game. - -Through our SDK implementation, we give you the power to generate a secure connection request that enables the user to create a connection between their in-game profile and Beam identity account (the in-app user). - - - - - - - - Make sure you connect to Beam testnet in order to implement the application - during your development process. You can switch to testnet by switching on the - log-in screen of the app. - - -### Integrate the app - -Unlock the full potential for your user by implementing the Beam Companion app in a couple of simple steps. - -- [Connecting your users](/service/companion/connecting-your-users): Create the connection through a QR code or deeplink - -- [Verifying connections](/service/companion/verifying-webhooks): Verify whenever a connection has been created diff --git a/pages/service/companion/verifying-webhooks.mdx b/pages/service/companion/verifying-webhooks.mdx deleted file mode 100644 index 5e9a3a6..0000000 --- a/pages/service/companion/verifying-webhooks.mdx +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: Verifying connections ---- - -# Verify user connections - -After user scans the QR code and connects their user-account to the profile, you will receive an incoming webhook on the provided callbackUrl. - -```typescript -const request = await beam.profiles.createConnectionRequest("profile-id", { - callbackUrl: - "https://your-games-backend.your-game.com/api/incoming-webhook/:profile-id", -}); -``` - -The incoming webhook doesn't tell you to which user a profile is linked to, but it does confirm to you that a link was made between the app-user and your game's profile. - -### Verify the incoming request - -When the incoming webhook arrives, there will be a `Signature` header included in it. The signature can be ignored completely, but allows you to verify whenever the incoming request we send you indeed is coming from Beam. The implementation for handling this signature are environment specific and you are required to use [Libsodium](https://doc.libsodium.org/). Below you will find an example on how to verify the signature within a Node.js based backend. - -```typescript -import * as sodium from "sodium-native"; - -export const verifySignature = ( - incomingRequestBody: Record, // The request body of the incoming webhook - incomingRequestHeaderSignature: string, // The 'signature' header of the incoming webhook - yourApiKey: string // The api key you've used to create the connection request -): boolean => { - const payloadString = JSON.stringify(incomingRequestBody); - const payloadBuffer = Buffer.from(payloadString, "utf8"); - const signature = Buffer.from(incomingRequestHeaderSignature, "hex"); - const secretBuffer = Buffer.from(yourApiKey, "utf8"); - - return sodium.crypto_auth_verify(signature, payloadBuffer, secretBuffer); // will return `true` or `false` -}; -``` diff --git a/pages/service/environments.mdx b/pages/service/environments.mdx index fb8be1d..d63f03c 100644 --- a/pages/service/environments.mdx +++ b/pages/service/environments.mdx @@ -14,7 +14,7 @@ Once you are ready to deploy your game to mainnet, simply request the production https://api.onbeam.com ```` -## api keys and environments +### API keys and environments Keep in mind that keys are not interchangeable per environment, meaning that you will need to send the correct key in the `x-api-key` header based on the hostname you use. diff --git a/pages/service/exchange/introduction.mdx b/pages/service/exchange/introduction.mdx index 2c501f5..8b64076 100644 --- a/pages/service/exchange/introduction.mdx +++ b/pages/service/exchange/introduction.mdx @@ -8,11 +8,6 @@ import { Callout } from "nextra/components"; The API allows you to convert any in-game tokens or BEAM associated with a profile, using Beam's decentralized exchange swap.onbeam.com. Conversion rates are determined via an Automated Market Maker mechanism, and depend on supply and demand of the respective tokens. You can learn more about setting up a liquidity pool for your own tokens here, in order to enable trading. -### Roadmap - -Throughout the coming months, we'll be releasing additional features that will help you to provide a more complete marketplace experience, with features ranging from programmatic offers, auctions and extensive filtering options to allow you to create a full-fledged in-game marketplace solely by relying on the Beam marketplace. - - Feel like something is missing, and needs to be prioritized? Check out our - [2024 roadmap](/service/roadmap) or let's have a chat through build@onbeam.com + Feel like something is missing, and needs to be prioritized? Let's have a chat through build@onbeam.com! diff --git a/pages/service/full-api-reference.mdx b/pages/service/full-api-reference.mdx index f2f617f..8bdb979 100644 --- a/pages/service/full-api-reference.mdx +++ b/pages/service/full-api-reference.mdx @@ -6,14 +6,31 @@ The Beam API is a RESTful API. Given you have obtained your api key, you are abl If you ever feel the need to access all of the available endpoints directly from our deployed service, you can use the following links +### Automation API + +```md filename="Swagger UI" +https://api.testnet.onbeam.com/api/automation +``` + +```md filename="OpenAPI specification (JSON)" +https://api.testnet.onbeam.com/api/automation-json +``` + +```md filename="OpenAPI specification (YAML)" +https://api.testnet.onbeam.com/api/automation-yaml +``` + + +### Player API + ```md filename="Swagger UI" -https://api.testnet.onbeam.com/api/game +https://api.testnet.onbeam.com/api/player ``` ```md filename="OpenAPI specification (JSON)" -https://api.testnet.onbeam.com/api/game-json +https://api.testnet.onbeam.com/api/player-json ``` ```md filename="OpenAPI specification (YAML)" -https://api.testnet.onbeam.com/api/game-yaml +https://api.testnet.onbeam.com/api/player-yaml ``` diff --git a/pages/service/game/api-keys.mdx b/pages/service/game/api-keys.mdx index f428a6e..331e8f5 100644 --- a/pages/service/game/api-keys.mdx +++ b/pages/service/game/api-keys.mdx @@ -13,7 +13,7 @@ Note that, as soon as you regenerate the keys, your existing keys will be invali Below you'll find an example on how to regenerate your API keys. ```typescript -import { Beam } from "@onbeam/node"; +import { Beam } from "@onbeam/automation-api-client"; const beam = new Beam("x-regenerate-api-key"); diff --git a/pages/service/game/introduction.mdx b/pages/service/game/introduction.mdx index 1b1d675..3bc500f 100644 --- a/pages/service/game/introduction.mdx +++ b/pages/service/game/introduction.mdx @@ -23,7 +23,7 @@ If you're just interested in the currently registered information of your game i **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"; +import { Beam } from "@onbeam/automation-api-client"; const beam = new Beam("x-api-key"); diff --git a/pages/service/game/managing-contracts.mdx b/pages/service/game/managing-contracts.mdx index db8ff64..b4438a8 100644 --- a/pages/service/game/managing-contracts.mdx +++ b/pages/service/game/managing-contracts.mdx @@ -2,7 +2,7 @@ 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 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/automation) to simply add the necessary contracts to your game. --- @@ -17,7 +17,7 @@ If you're using the [Beam Companion](/service/companion/introduction) app, it mi Adding a contract is as simple as calling the `addContractToGame` method. ```typescript -import { Beam } from "@onbeam/node"; +import { Beam } from "@onbeam/automation-api-client"; const beam = new Beam("x-api-key"); @@ -69,7 +69,7 @@ const contract = beam.game.addContractToGame({ Removing a contract from your game is just as simple, simply use the `removeContractFromGame` method to remove it. ```typescript -import { Beam } from "@onbeam/node"; +import { Beam } from "@onbeam/automation-api-client"; const beam = new Beam("x-api-key"); diff --git a/pages/service/game/updating-game.mdx b/pages/service/game/updating-game.mdx index 767690f..c13e18d 100644 --- a/pages/service/game/updating-game.mdx +++ b/pages/service/game/updating-game.mdx @@ -15,7 +15,7 @@ If you're using the [Beam Companion](/service/companion/introduction) app, it mi Updating your game is as simple as calling the `updateGame` method. ```typescript -import { Beam } from "@onbeam/node"; +import { Beam } from "@onbeam/automation-api-client"; const beam = new Beam("x-api-key"); diff --git a/pages/service/implementation-self-custody.mdx b/pages/service/implementation-self-custody.mdx new file mode 100644 index 0000000..77a130d --- /dev/null +++ b/pages/service/implementation-self-custody.mdx @@ -0,0 +1,62 @@ +--- +title: Implementation +--- + +import { Cards, Card } from "nextra-theme-docs"; + +# Implementing Beam + +The implementation of our new self-custodial service consists of two components + +- The Beam game-platform client. We currently solely provide a **C# sdk** meant to be implemented in the **Unity**. In the future, we will be releasing more implementations for various platforms. +- The server client. We currently provide a **C# and Typescript** clients. + +In the near future, we expect to expand the platform clients with all the self-custody client methods, giving you more flexibility on how you want to implement Beam in your game. + +--- + +### The platform client (Unity) + +The platform client contains helpers to get users started with Beam within your game. + + + + + +#### Initialize the platform client + +In order to interact with these clients, you will need a new type of API key - the `Publishable` API key. You will be able to find this API key by regenerating your API keys through the existing API. You can do so programmatically, or by interacting with the method in the [OpenAPI / Swagger UI](https://api.testnet.onbeam.com/api/automation#/Game/regenerateApiKeys) interface. + + +```csharp +var beamClient = gameObject.AddComponent() + .SetBeamApiKey("your-publishable-api-key") // set your Publishable(!) API key + .SetEnvironment(BeamEnvironment.Testnet) // defaults to Testnet + .SetDebugLogging(true) // optional, defaults to false + .SetStorage(yourCustomStorageImplementation); // optional, defaults to PlayerPrefs storage; +``` + +--- + +### The request client + +The request client is a new client which can be used to generate [Operations](/service/operations/introduction). Both the request clients we offer for the self-custodial services, are structured in similar fashion to the existing SDKs that offer custodial [Profiles](/service/profiles/introduction). + +Keep in mind that we expect you to also use the `Publishable` API key in these clients. + + + + + \ No newline at end of file diff --git a/pages/service/index.mdx b/pages/service/index.mdx index e43b9ea..dcee86d 100644 --- a/pages/service/index.mdx +++ b/pages/service/index.mdx @@ -20,25 +20,20 @@ Once the asset contracts are deployed, we're able to index them from Beam and ex --- -### Step 3 - Obtain your API key +### Step 3 - Obtain your API keys -Obtain your API key. If you haven't received any API key yet, please contact build@onbeam.com. +Obtain your API keys. If you haven't received any API key yet, please contact build@onbeam.com. --- ### Step 4 - Pick an implementation strategy -Pick an implementation strategy. You can either connect to the HTTP API directly, or use [one of our provided SDKs](https://github.com/Merit-Circle/beam-sdk). We currently provide a [Node.js (Typescript)](https://www.npmjs.com/package/@onbeam/node) and [C# (RestSharp)](https://www.nuget.org/packages/Beam) SDK, but are happy to provide you with a client based on whatever language you need to support +Pick an implementation strategy. You can either connect to the HTTP API directly, or use [one of our provided SDKs](https://github.com/Merit-Circle/beam-sdk). We currently provide a [Node.js (Typescript)](https://www.npmjs.com/package/@onbeam/automation-api-client) and [C# (RestSharp)](https://www.nuget.org/packages/Beam) SDK, but are happy to provide you with a client based on whatever language you need to support --- ### Step 5 - Implement Beam -Implement Beam in your backend. Get started with one of our guides or choose a strategy of your own. We recommend you to get familiar with the terminology in Beam, starting with [Profiles](/service/profiles/introduction). - - - Please be aware the services described in this documentation are bound to - change in the future. - +Implement Beam in your game. Get started with one of our guides or choose a strategy of your own. We recommend you to get familiar with the terminology in Beam, starting with [Profiles](/service/profiles/introduction). diff --git a/pages/service/introduction-managed.mdx b/pages/service/introduction-managed.mdx new file mode 100644 index 0000000..2933696 --- /dev/null +++ b/pages/service/introduction-managed.mdx @@ -0,0 +1,27 @@ +--- +title: Managed +--- + +# Introduction to managed services + +Through the managed services, you're able to create [Profiles](/service/profiles/introduction) to control assets and distribute them to your users. + +--- + +### What is the managed service? + +The managed service in Beam is, in technical design, very similar to our [self-custody](/service/introduction-self-custody) solution. The key difference is that the managed services are exactly what the name says - they are managed, by us (and yourself). Through the `Secret` API key, you will be able to create [Profiles](/service/profiles/introduction) and manage assets accordingly. + +--- + +### Disclaimer + +It's important to understand that the managed service and it's features are **not meant to be used to control user assets**. If you are looking to implement parts of our service to do that, please refer to our [self-custody](/service/introduction-self-custody) solution. + +--- + +### Getting started with self custody + +- [Profiles](/service/profiles/introduction): Understand the role of Profiles as your players' on-chain inventories and more. +- [Policies](/service/policies/introduction): Understanding and creating policies. +- [Trading](/service/trading/introduction): Trade assets and tokens between two profiles securely. diff --git a/pages/service/self-custody/introduction.mdx b/pages/service/introduction-self-custody.mdx similarity index 77% rename from pages/service/self-custody/introduction.mdx rename to pages/service/introduction-self-custody.mdx index 8da0f59..29bdfc6 100644 --- a/pages/service/self-custody/introduction.mdx +++ b/pages/service/introduction-self-custody.mdx @@ -6,19 +6,27 @@ title: Self-custody Through our new self-custody implementation, you are able to set up self-custodial users with Beam. The implementation is a new service that works based on self-custodial private keys, and newly deployed account abstractions. Existing [Profiles](/service/profiles/introduction) that you created, won't be available in this new service. +--- ### What is self custody? Self-custody means that in this new implementation, a private key only controllable by the user can sign for transactions. The private key for each user is generated in the browser when they start interacting with [Sessions](/service/sessions/introduction) and [Operations](/service/operations/introduction). When they do, they will be required to authorize with a social identity, from which a private key is generated and sharded - and securely stored. +--- + ### Disclaimer Our self-custodial implementation is **subject to change**, while the basis of the implementation will remain more or less the same, we have different improvements in mind that will make the experience even better - for both you (the game developer) and the end user. +--- ### Getting started with self custody - [Implementation](/service/self-custody/implementation): How to get started - [Operations](/service/operations/introduction): An introduction to Operations - [Sessions](/service/sessions/introduction): An introduction to Sessions +- [Transactions](/service/transactions/introduction): Understand how to run sponsored, self-paid and custom charge transactions. +- [Assets](/service/assets/introduction): Simplify in-game asset management. +- [Marketplace](/service/marketplace/introduction): List, buy and make offers on other peoples assets. +- [Exchange](/service/exchange/introduction): Convert tokens based on configured liquidity pools. diff --git a/pages/service/managed-or-self-custody.mdx b/pages/service/managed-or-self-custody.mdx new file mode 100644 index 0000000..ebc599c --- /dev/null +++ b/pages/service/managed-or-self-custody.mdx @@ -0,0 +1,32 @@ +--- +title: Self-custody or managed +--- + +# Self-custody or managed + +Through various iterations of the Beam API, we realised the need to expand our services with a self-custodial solution for users. + +--- + +### When to use the self-custody service? + +If you're looking to implement Beam in your game, we highly recommend you to get started with our [self-custody](/service/introduction-self-custody) solution. We offer various clients to implement this service on both the server as well as the client side, and since the user controls the private key which owns the account abstractions we deploy, there are no doubts about who owns the asset - it's the gamer. + +- [Implementation](/service/implementation-self-custody): How to get started +- [Operations](/service/operations/introduction): An introduction to Operations +- [Sessions](/service/sessions/introduction): An introduction to Sessions +- [Transactions](/service/transactions/introduction): Understand how to run sponsored, self-paid and custom charge transactions. +- [Assets](/service/assets/introduction): Simplify in-game asset management. +- [Marketplace](/service/marketplace/introduction): List, buy, and make offers on other people's assets. +- [Exchange](/service/exchange/introduction): Convert tokens based on configured liquidity pools. + +--- + +### When to use the managed service? + +While the [self-custody](/service/introduction-self-custody) solution offers everything need to get you going, you might be interested in a programmatic solution for various back-end purposes. For example: if you're looking to create a programmatic minter which you can control through one of our clients, the managed service is the one you're looking for. + + +- [Profiles](/service/profiles/introduction): Understand the role of Profiles as your players' on-chain inventories and more. +- [Policies](/service/policies/introduction): Understand and create policies. +- [Trading](/service/trading/introduction): Trade assets and tokens between two profiles securely. diff --git a/pages/service/marketplace/introduction.mdx b/pages/service/marketplace/introduction.mdx index 5153377..4dbfee5 100644 --- a/pages/service/marketplace/introduction.mdx +++ b/pages/service/marketplace/introduction.mdx @@ -24,6 +24,5 @@ In order to create a full marketplace integration it is important to understand Throughout the coming months, we'll be releasing additional features that will help you provide a more complete marketplace experience, with features ranging from programmatic offers, auctions and extensive filtering options to allow you to create a full-fledged in-game marketplace solely by relying on the Beam marketplace. - Feel like something is missing, and needs to be prioritized? Check out our - [2024 roadmap](/service/roadmap) or let's have a chat through build@onbeam.com + Feel like something is missing, and needs to be prioritized? Let's have a chat through build@onbeam.com! diff --git a/pages/service/operations/_meta.json b/pages/service/operations/_meta.json index 314cc5e..cf54669 100644 --- a/pages/service/operations/_meta.json +++ b/pages/service/operations/_meta.json @@ -1,4 +1,5 @@ { "introduction": "Introduction", - "creating-operations": "Creating operations" + "creating-operations": "Creating operations", + "processing-operations": "Processing operations" } diff --git a/pages/service/operations/creating-operations.mdx b/pages/service/operations/creating-operations.mdx index 62bca9c..8010825 100644 --- a/pages/service/operations/creating-operations.mdx +++ b/pages/service/operations/creating-operations.mdx @@ -6,7 +6,7 @@ title: Creating operations When you would like to transfer an asset that is owned by your user, you will need to ask them to sign for the transaction involved. -In order to do this, you need to initiate an Operation. Initiating an Operation is as simple as calling a method on the server client for the self-custodial API. If the thing you're trying to do requires the user to sign a transaction, an Operation will be returned. +In order to do this, you need to initiate an Operation. Initiating an Operation is as simple as calling a method on the server client for the Player API. If the thing you're trying to do requires the user to sign a transaction, an Operation will be returned. To make this a bit more tangible, here's a call you might make. At the bottom you will find an Operation response. **Disclaimer:** [Operations](/service/operations/introduction) will remain valid for a 24-hour time period, after which they will be removed / cleaned up. @@ -18,7 +18,7 @@ beamClient.TransferAsset('entity-id-of-user', { receiverEntityId: "receiver-entity-id-of-user", assetAddress: "0x9eeaecbe2884aa7e82f450e3fc174f30fc2a8de3", tokenId: 23 -}) +}); // { // "status": "Pending", diff --git a/pages/service/operations/processing-operations.mdx b/pages/service/operations/processing-operations.mdx index a96e0f3..785b294 100644 --- a/pages/service/operations/processing-operations.mdx +++ b/pages/service/operations/processing-operations.mdx @@ -9,18 +9,27 @@ After you created an Operation, the operation needs to be signed for. You could ### Using our SDK -When using our SDK, processing an operation is as simple as providing the user entity id and the operation id. The `SignOperation` method will automatically open a browser. +When using our SDK, processing an operation is as simple as providing the user entity id and the operation id. The `SignOperation` method will automatically open a browser or sign it with an existing Session. ```csharp -StartCoroutine(beamClient.SignOperation("entity-id-of-user", "operation-id-of-api", result => - { - // handle the result here - }, - chainId: 13337, // defaults to 13337 - secondsTimeout: 240, // timeout in seconds for getting a response in case browser flow was chosen - fallBackToBrowser: true // if true, opens a browser for the user to sign the operation if Session was not started -)); +StartCoroutine(m_BeamClient.SignOperation( + "entityIdOfYourUser", + operationId, // operationId from Beam API + actionResult => + { + if (actionResult.Status == BeamResultType.Success) + { + // you can now check for actual Status of the signing f.e.: + var isApproved = actionResult.Result == BeamOperationStatus.Executed; + var isRejected = actionResult.Result == BeamOperationStatus.Rejected; + // (...) + } + }, + chainId: 13337, // optional chainId, defaults to 13337 + fallbackToBrowser: true, // if true, will automatically open browser for the user to sign the operation, if there is no valid session + secondsTimeout: 240 // timeout in seconds for getting a result of message signing from the browser, used if there was no valid session + )); ``` @@ -28,25 +37,24 @@ StartCoroutine(beamClient.SignOperation("entity-id-of-user", "operation-id-of-ap As you might have seen when creating an Operation, we return a `url` property in the response. The `url` is a URL to our web interface, which the user can use in order to sign for the Operation. -Please note that if you use the web interface, we won't provide you with a proper callback about the status of the Operation. You will need to poll our APIs' `getOperation` method periodically in order to know about status changes in the Operation based on user actions. +Please note that if you use the web interface, we won't provide you with a proper callback about the status of the Operation. You will need to poll our API's [getOperation](https://api.testnet.onbeam.com/api/player#/Operation/getOperation) method periodically in order to know about status changes in the Operation based on user actions. ```csharp - -// { -// "status": "Pending", -// "id": "clwt0h7ej000c2jckyr2nh0cv", -// "createdAt": "2024-05-30T08:46:42.620Z", -// "updatedAt": null, -// "gameId": "cltr8rde601aeakka28hbtuim", -// "userId": "clwdehitt005biwog2szib1fh", -// "chainId": 13337, -// "url": "https://identity.testnet.onbeam.com/games/cltr8rde601aeakka28hbtuim/operation/clwt0h7ej000c2jckyr2nh0cv/confirm", -// "game": { -// ... -// }, -// "transactions": [ -// .. -// ] -// } +// { +// "status": "Pending", +// "id": "clwt0h7ej000c2jckyr2nh0cv", +// "createdAt": "2024-05-30T08:46:42.620Z", +// "updatedAt": null, +// "gameId": "cltr8rde601aeakka28hbtuim", +// "userId": "clwdehitt005biwog2szib1fh", +// "chainId": 13337, +// "url": "https://identity.testnet.onbeam.com/games/cltr8rde601aeakka28hbtuim/operation/clwt0h7ej000c2jckyr2nh0cv/confirm", +// "game": { +// ... +// }, +// "transactions": [ +// ... +// ] +// } ``` diff --git a/pages/service/profiles/_meta.json b/pages/service/profiles/_meta.json index 3a5c295..ebf534b 100644 --- a/pages/service/profiles/_meta.json +++ b/pages/service/profiles/_meta.json @@ -1,7 +1,6 @@ { "introduction": "Introduction", "creating-profiles": "Creating profiles", - "users-and-profiles": "Users and profiles", "match-profiles": "Match profiles", "minting-profiles": "Minting profiles", "treasury-profiles": "Treasury profiles" diff --git a/pages/service/profiles/creating-profiles.mdx b/pages/service/profiles/creating-profiles.mdx index e1088a7..a5f0c4d 100644 --- a/pages/service/profiles/creating-profiles.mdx +++ b/pages/service/profiles/creating-profiles.mdx @@ -8,13 +8,12 @@ const profile = await beam.profiles.createProfile({ entityId: "some-string-uniqu A couple of examples what this ID could contain: -- A hashed string representing the in-game ID you use on the application -- An account ID by your SSO provider -- An e-mail address (not recommended for privacy reasons) +- An ID representing an entity in your own service (for example: a match ID) +- A pre-defined constant, eg; 'Minter' -It's up to you! But consider this carefully: in case of an application emergency on your end, you will want to be able to restore which player in your game owns which profile(s), hence our recommendation using an identifier which you already have for each player, preventing from having to store it. +It's up to you! But consider this carefully: in case of an application emergency on your end, you will want to be able to restore a mapping to the correct Profiles, hence our recommendation using an identifier which you already have, preventing from having to store it. -The `EntityID` you provide to us, is included in most Profile related responses as the `externalEntityId`, should you ever need to refer to it. +The `entityId` you provide to us, is included in most Profile related responses as the `externalEntityId`, should you ever need to refer to it. ## Profiles on chain diff --git a/pages/service/profiles/introduction.mdx b/pages/service/profiles/introduction.mdx index 00d957c..33b93c2 100644 --- a/pages/service/profiles/introduction.mdx +++ b/pages/service/profiles/introduction.mdx @@ -6,18 +6,11 @@ title: Introduction to Profiles As you are implementing Beam into your product, the first interaction you will most likely have with our SDK are with Profiles. Profiles can have different purposes and meaning depending on your games. -The most obvious purpose for Profiles is to serve as an on-chain inventory for your player, but they are able to serve other purposes. Profiles within Beam are on-chain [account abstractions](https://ethereum.org/en/roadmap/account-abstraction/) that possibly will, or possibly will not contain assets - controlled by the api key we provided you. - -Note that there is no relationship between an actual player within your game and a profile - unless you purposefully create the relationship. You could allow users to obtain control over a profile by [allowing them to link up to it](/service/profiles/users-and-profiles), or you could make profiles serve as a [match escrow wallet](/service/profiles/match-profiles). Another use case would be [minting profiles](/service/profiles/minting-profiles), allowing you to mint-on demand through the SDK. +Profiles are on-chain [account abstractions](https://ethereum.org/en/roadmap/account-abstraction) that possibly will, or possibly will not contain assets - controlled by the `Secret` API key we provided you. Please note that - while technically possible - Profiles **are not meant to contain any user assets**. If you're looking for a solution to manage user asserts, please look into our [self-custody](/service/introduction-self-custody) solution. In order to full understand Profiles it is important to understand all of the possibilities that you have, here are some articles to get you started: - [Creating profiles](/service/profiles/creating-profiles): Creating profiles based on an identifier - -- [Users and profiles](/service/profiles/users-and-profiles): Connect your users to their Profile - - [Match profiles](/service/profiles/match-profiles): Match profiles (escrow-style games) - - [Minting profiles](/service/profiles/minting-profiles): For minting assets on demand - - [Treasury profiles](/service/profiles/treasury-profiles): For distributing pre-minted assets diff --git a/pages/service/profiles/match-profiles.mdx b/pages/service/profiles/match-profiles.mdx index 1993350..3652d6a 100644 --- a/pages/service/profiles/match-profiles.mdx +++ b/pages/service/profiles/match-profiles.mdx @@ -2,7 +2,7 @@ One of the less obvious use-cases for profiles is using them for escrow. A common scenario in Web3 games are games where players put their assets on the line. Every player can participate in a PvP-match, but has to put one of their assets on the line - and you don't want players to be able to simply disconnect or moving their assets through the companion app right before they lose a match. -It could make sense to create a profile for these types of PvP matches - requiring everyone who wants to join a match to send one of their assets into said match profile. As the match profile was never [linked to a user](/service/profiles/users-and-profiles), it remains in your custody as the game developer - offering no way for users to further interact with these assets up until the point that you send them back to their player-profile. +It could make sense to create a profile for these types of PvP matches - requiring everyone who wants to join a match to send one of their assets into said match profile. Let's go through the steps you would need to take in order to properly set this up within by providing an actual scenario. In our scenario, Player A wants to create a 1v1 PvP match where the winner takes all. They go through the game's interface for creating a match and set-up the rules/preferences for that match. @@ -36,7 +36,7 @@ const playerAssets = await beam.assets.getProfileAssets("your-player-a-id", { }); ``` -Once both players selected their assets, they need to be moved to the match profile. When transfer is completed, the assets are outside of players' control. Note that at the moment of writing we don't offer a way to 'listen' to on-chain events, but as per our [roadmap](/service/roadmap), we are aiming to have this ready during 2024. +Once both players selected their assets, they need to be moved to the match profile. When transfer is completed, the assets are outside of players' control. Transferring player A their asset: diff --git a/pages/service/profiles/treasury-profiles.mdx b/pages/service/profiles/treasury-profiles.mdx index 6a54e39..fce0efe 100644 --- a/pages/service/profiles/treasury-profiles.mdx +++ b/pages/service/profiles/treasury-profiles.mdx @@ -21,6 +21,4 @@ const treasury = await beam.profiles.createProfile({ entityId: "your-treasury-id The treasury profile would be a profile like any other: an account abstraction that is within your control authorized through the API key. By us adding the contracts for your pre-minted assets to your game, and you sending the pre-minted assets to the treasury's profile wallet address, you essentially allow yourself to move these assets around from the profile to any other of your profiles through our sdk. -By never creating a connection request for this profile as described in the [users and profiles](/service/profiles/users-and-profiles), you won't have a risk of anyone touching the assets within the profile except for someone authorized by the API keys. - If pre-minted assets get distributed in batches, you might want to create a treasury profile per batch - or periodically send assets to the profile's wallet address - managing these profiles is up to you. Do keep in mind that everyone who possesses or is able to get access to the read-and-write API key we provided to you, is able to move around these assets freely between profiles of your game. diff --git a/pages/service/profiles/users-and-profiles.mdx b/pages/service/profiles/users-and-profiles.mdx deleted file mode 100644 index 590da1b..0000000 --- a/pages/service/profiles/users-and-profiles.mdx +++ /dev/null @@ -1,54 +0,0 @@ -# Users and profiles - -What is important to understand is that the Profiles entity within Beam is not exclusively a matter of players. Profiles could be used for various purposes, one of which is [match profiles](/service/profiles/match-profiles). - -However - in our opinion - it makes a ton of sense to create a Profile for each of your players as soon as you want something to happen on-chain. You can use these player profiles to manage a user and their assets. On-chain tokens they earned (or bought), NFTs they minted (or you minted on their behalf) all can be sent to the player profile for each player. - -In order to allow players to see and manage their assets outside of your game, we offer a way to link-up their profile to an SSO authenticated user identity. While it's not required, the companion app offers an extension of the web3 experience where users are able to manage, give away and trade assets, without you having to facilitate this. - -### Connection request - -If you want to allow players to control their assets outside of your game, providing them the web3 experience, you would need to create a connection request for a profile. - -```typescript -const request = await beam.profiles.createConnectionRequest("your-player-id", { - callbackUrl: - "https://your-games-backend.your-game.com/api/incoming-webhook/your-player-id", -}); - -// { -// "id": "string", -// "challenge": "c5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470", -// "validUntil": "2023-08-30T08:35:08+00:00" -// } -``` - -The `challenge` property that we send you when you created this Connection request is essentially a key meant solely for the player behind the profile you want to link up to a user within Beam. - -The next step is allowing the user to obtain the challenge we created within the app, as this challenge enables up to create the connection. - -- If your game is running on a console, PC or within a browser - we recommend you to encode the challenge in a QR code -- If your game is running on iOS or Android, you could pass the challenge down a deeplink that opens up the Beam companion app - -The user will scan the QR code with the companion app, which is how we create a relationship between the user in Beam and the player profile you've registered. By providing a `callbackUrl` when creating a Connection request, we'll be able to provide you with an incoming webhook telling you that a profile was linked up to a user. - -### Verifying the incoming webhook - -The incoming webhook doesn't tell you to which user a profile is linked to, but it does confirm to you that a link was made between the app-user and your game's profile. When the incoming webhook arrives, there will be a `Signature` header included in it. The signature can be ignored completely, but allows you to verify whenever the incoming request we send you indeed is coming from Beam. The implementation for handling this signature are environment specific and you are required to use [Libsodium](https://doc.libsodium.org/). Below you will find an example on how to verify the signature within a Node.js based backend. - -```typescript -import * as sodium from "sodium-native"; - -export const verifySignature = ( - incomingRequestBody: Record, // The request body of the incoming webhook - incomingRequestHeaderSignature: string, // The 'signature' header of the incoming webhook - yourApiKey: string // The api key you've used to create the connection request -): boolean => { - const payloadString = JSON.stringify(incomingRequestBody); - const payloadBuffer = Buffer.from(payloadString, "utf8"); - const signature = Buffer.from(incomingRequestHeaderSignature, "hex"); - const secretBuffer = Buffer.from(yourApiKey, "utf8"); - - return sodium.crypto_auth_verify(signature, payloadBuffer, secretBuffer); // will return `true` or `false` -}; -``` diff --git a/pages/service/roadmap.mdx b/pages/service/roadmap.mdx deleted file mode 100644 index 3daadef..0000000 --- a/pages/service/roadmap.mdx +++ /dev/null @@ -1,22 +0,0 @@ -import { Callout } from "nextra/components"; - -# Upcoming features - -Throughout time, we'll be working hard to provide additional features within the Beam accounts API or related products (like the Beam marketplace). - -As we are working with multiple game development studios in order to ensure the success of Beam and the integration of it within the developers their games, we will shift more granular priorities throughout time as we see fit to ensure partners success. Therefore, the roadmap serves as a set of handlebars - not an exact promise. - - - Feel like something is missing, and needs to be prioritized? Let's have a chat - through build@onbeam.com - - -## 2024 and beyond - -- On-chain event subscriptions through Queues - 1. Allowing game devs to listen to on-chain actions taken by users outside of the game developers control - 2. Allowing game devs to be aware of transactions being completed without having to implement polling -- A Beam provided identity solution - 1. Allowing game devs to implement 'Log-in with Beam' without them having to implement their own authentication solution - 2. Log-in works through scanning a QR code generated through the Beam sdk, scanned by the user within the Beam companion app -- A companion app feature called Beam Vaults, which will be a self-custodial solution for users to interact with their assets diff --git a/pages/service/sdk.mdx b/pages/service/sdk.mdx index a6f20d2..889abfe 100644 --- a/pages/service/sdk.mdx +++ b/pages/service/sdk.mdx @@ -1,10 +1,10 @@ import { Callout, Cards, Card } from "nextra/components"; -# Beam Accounts SDK +# Beam API clients -The recommended way to interact with the Beam API is by using one of our official SDKs. All of the provided SDKs are meant to be used **server side**, as it's crucial to not expose any of the api keys we provided publicly. +The recommended way to interact with the Beam API is by using one of our official clients. -At the time of writing, the SDKs we're shipping are all automatically generated after every service release. We're currently using [OpenAPI generator](https://openapi-generator.tech/) and [OpenAPI Typescript Codegen](https://www.npmjs.com/package/openapi-typescript-codegen). +At the time of writing, the clients we're shipping are all automatically generated after every service release. We're currently using [OpenAPI generator](https://openapi-generator.tech/) and [OpenAPI Typescript Codegen](https://www.npmjs.com/package/openapi-typescript-codegen). It's of the utmost importance that your API key never gets exposed. If your @@ -15,43 +15,66 @@ At the time of writing, the SDKs we're shipping are all automatically generated --- -### Beam SDKs +### API clients -In order to get started, we currently provide the following SDKs. Note that if there's no available SDK available for your preferred language, there's always the possibility of directly connecting to the RESTful endpoints by passing your API key in the `x-api-key` header. +In order to get started, we currently provide the following clients. Note that if there's no available client available for your preferred language, there's always the possibility of directly connecting to the RESTful endpoints by passing your API key in the `x-api-key` header. + + +#### Automation API clients + +All of the Automation API clients are meant to be used **server side**, as it's crucial to not expose any of the api keys we provided publicly. + + + +#### Player API clients + +The Player API clients can be used in the client, as the API that is required to interact with the self-custody services can be exposed without risk. + + + --- -### Beam SDK repository +### Beam clients repository -If you're interested in how we generate the SDK, have a look at the [Github repository](https://github.com/Merit-Circle/beam-sdk). If you don't want to use our provided SDKs, it might still be of inspiration. +If you're interested in how we generate the clients, have a look at the [Github repository](https://github.com/Merit-Circle/beam-api-clients). If you don't want to use our provided clients, it might still be of inspiration. --- ### Releases -If you are interested in more granular changelogs for SDK releases, have a look at our [Github releases](https://github.com/Merit-Circle/beam-sdk/releases) +If you are interested in more granular changelogs for SDK releases, have a look at our [Github releases](https://github.com/Merit-Circle/beam-api-clients/releases) -Every deployment of the Beam API leads to a new **patch** version of the SDK being released. With every release, the release description in the Github release contains a description that explains the difference between the previous and new version based on the REStful endpoints. +Every deployment of the Beam API leads to a new **patch** version of the clients being released. With every release, the release description in the Github release contains a description that explains the difference between the previous and new version based on the REStful endpoints. In the future, we hope to automatically assess major, minor and patch versions, but we currently rely on patch incrementals only. --- -### Beam OpenAPI Specification +### Beam OpenAPI specification -Beam OpenAPI specification empowers you with a broad set of developer tooling, starting with Postman collections and generating your own SDK. It also serves as the basis for our generated release changelogs and SDKs. +Beam OpenAPI specification empowers you with a broad set of developer tooling, starting with Postman collections and generating your own SDK. It also serves as the basis for our generated release changelogs and clients. -[Beam OpenAPI Specification](https://api.testnet.onbeam.com/api/game-json) +- [Beam Automation OpenAPI specification](https://api.testnet.onbeam.com/api/automation-json) +- [Beam Player OpenAPI specification](https://api.testnet.onbeam.com/api/player-json) diff --git a/pages/service/self-custody/_meta.json b/pages/service/self-custody/_meta.json deleted file mode 100644 index e307077..0000000 --- a/pages/service/self-custody/_meta.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "introduction": "Introduction", - "implementation": "Implementation" -} diff --git a/pages/service/self-custody/implementation.mdx b/pages/service/self-custody/implementation.mdx deleted file mode 100644 index b233a1f..0000000 --- a/pages/service/self-custody/implementation.mdx +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Implementation ---- - -import { Cards, Card } from "nextra-theme-docs"; - -# Getting started with the implementation - -The implementation of our new self-custodial service consists of two components - -- The client side component. We currently solely provide a **C# sdk** meant to be implemented in the **Unity**. In the future, we will be releasing more implementations for various platforms. -- The server client. We currently provide a **C# and Typescript** server client. - - -In the near future, we expect to expand the client side component with all the server client methods, so that you also have the option to implement completely in the client. - - -### Initialize the client side sdk - -In order to initialize the Unity (C# client sdk), you will need a new type of API key - the `Publishable` API key. You will be able to find this API key by regenerating your API keys through the existing API. You can do so programmatically, or by interacting with the method in the [OpenAPI / Swagger UI](https://api.testnet.onbeam.com/api/game#/Game/regenerateApiKeys) interface. - - -```csharp - -var beamClient = gameObject.AddComponent() - .SetBeamApiGame("your-game-id", "your-publishable-api-key") - .SetEnvironment(BeamEnvironment.Testnet); -``` - - -### Server client - -The server client is a new client which can be used to generate [Operations](/service/operations/introduction). Both server clients we offer for the new self-custodial services, are structured in similar fashion to the existing SDKs that offer custodial [Profiles](/service/profiles/introduction). - -Keep in mind that we expect you to use the `Publishable` API key currently, on both the client-side and the server client when interacting with the self-custody service. - - - - - \ No newline at end of file diff --git a/pages/service/sessions/creating-sessions.mdx b/pages/service/sessions/creating-sessions.mdx index f06c01d..22126f0 100644 --- a/pages/service/sessions/creating-sessions.mdx +++ b/pages/service/sessions/creating-sessions.mdx @@ -4,27 +4,57 @@ title: Creating sessions # Creating sessions -In order to get started a Session going, you will need to call the following method on our C# sdk in the client. +In order to get started a Session going, you will need to call the following method on our C# SDK in the game client. **Disclaimer:** Sessions should only be created and initialised on the client side. ```csharp -StartCoroutine(beamClient.CreateSession("user-entity-id", result => - { - // handle the result here - }, - chainId: 13337, // defaults to 13337 - secondsTimeout: 240 // timeout in seconds for getting a result of Session signing from the browser -)); +StartCoroutine(beamClient.CreateSession( + "entityIdOfYourUser", + actionResult => + { + if (actionResult.Status == BeamResultType.Success) + { + var session = actionResult.Result; + // you now have an active session that can sign operations + } + }, + chainId: 13337, // optional chainId, defaults to 13337 + secondsTimeout: 240 // timeout in seconds for getting a result of Session signing from the browser + )); ``` The method handles a couple of things: -1. It generates a private key in the game client of the user +1. It generates a private key in the game client of the user and stores it locally.* 2. It opens a webview with a constructed url that guides the user through an authentication and authorization flow 3. If the user approves the session creation, the session gets authorized to sign for transactions on your users behalf - -Once handled, the session (private key) is able to sign transaction on behalf of the user. Note that, the session key is limited to run transactions for contracts that were added to your game in the first place. \ No newline at end of file +* NOTE: You can customize storage of Unity SDK using `beamClient.SetStorage()` method with your implementation of `IStorage`. It's important to keep the data on client side. + +Once handled, the session (private key) is able to sign transaction on behalf of the user. Note that, the session key is limited to run transactions for contracts that were added to your game in the first place. If a new contract was added to your game, calling `beamClient.GetActiveSession()` will no longer return that session as valid. + +## Retrieving an active Session + +You can retrieve current valid and active Session for your user. If local storage was cleared out, your game contracts changed, or the session simply expired - we will not return an active session. + +``` csharp +StartCoroutine(beamClient.GetActiveSession( + "entityIdOfYourUser", + actionResult => + { + if (actionResult.Status == BeamResultType.Success) + { + var session = actionResult.Result; + // you have an active session that can sign operations + } + else + { + // you need to create a session using CreateSession(), or User will sign operations using browser + } + }, + chainId: 13337 // optional chainId, defaults to 13337 + )); +``` \ No newline at end of file diff --git a/pages/service/sessions/introduction.mdx b/pages/service/sessions/introduction.mdx index 6224e9b..1268fde 100644 --- a/pages/service/sessions/introduction.mdx +++ b/pages/service/sessions/introduction.mdx @@ -6,12 +6,12 @@ title: Sessions A self-custody implementation for your users means that the ownership of the account abstraction used, is **owned** by the private key in control of the user. Every time you want to interact with the blockchain on the users' behalf, you will need to ask them to sign a transaction. -This experience can be obnoxious on its own - both for you as the developer and for the gamer. In order to minimize the friction involved, we worked on an implementation of session keys. +This experience can be obnoxious on its own - both for you as the developer and for the gamer. In order to minimize the friction involved, we offer Sessions. ### What is a session? -A session is, in essence, a **temporary authorized and limited-in-scope** private key, that can sign transactions on behalf of the self-custody account abstraction for your users. +A session is, in essence, a **temporary authorized and limited-in-scope** private key, that can sign transactions on behalf of the self-custodial account abstraction for your users. While this sounds intimidating, we created a useful abstraction in our newly released C# SDK that allows you to generate a session, and ask the user to authorize this session through a web interface. diff --git a/pages/service/sessions/signing-with-sessions.mdx b/pages/service/sessions/signing-with-sessions.mdx index 9d9ef85..56dbe23 100644 --- a/pages/service/sessions/signing-with-sessions.mdx +++ b/pages/service/sessions/signing-with-sessions.mdx @@ -7,16 +7,25 @@ title: Signing with sessions Once the session is successfully created, it's authorized to sign [Operations](/service/operations/introduction). As the game developer, you're simply able to apply the same method as was described in [Processing Operations](/service/operations/processing-operations). -If a session is active for the user, the session key is still available in the local storage of the game client and the session is authorized to sign - `beamClient.SignOperation` will automatically sign the Operation, without the user ever touching a browser. +If a session is active for the user, the session key is still available in the local storage of the game client and the session is authorized to sign - `beamClient.SignOperation()` will automatically sign the Operation, without having the user ever seeing a browser. ```csharp -StartCoroutine(beamClient.SignOperation("entity-id-of-user", "operation-id-of-api", result => - { - // handle the result here - }, - chainId: 13337, // defaults to 13337 - secondsTimeout: 240, // timeout in seconds for getting a response in case browser flow was chosen - fallBackToBrowser: true // if true, opens a browser for the user to sign the operation if Session was not started -)); +StartCoroutine(beamClient.SignOperation( + "entityIdOfYourUser", + operationId, // operationId from Beam API + actionResult => + { + if (actionResult.Status == BeamResultType.Success) + { + // you can now check for actual Status of the signing f.e.: + var isApproved = actionResult.Result == BeamOperationStatus.Executed; + var isRejected = actionResult.Result == BeamOperationStatus.Rejected; + // (...) + } + }, + chainId: 13337, // optional chainId, defaults to 13337 + fallbackToBrowser: true, // if true, will automatically open browser for the user to sign the operation, if there is no valid session + secondsTimeout: 240 // timeout in seconds for getting a result of message signing from the browser, used if there was no valid session + )); ``` \ No newline at end of file diff --git a/pages/service/sphere/creating-games.mdx b/pages/service/sphere/creating-games.mdx index a57b1b3..425c96a 100644 --- a/pages/service/sphere/creating-games.mdx +++ b/pages/service/sphere/creating-games.mdx @@ -7,7 +7,7 @@ title: Creating games When your game has more than one collection related to it on Sphere, it can make sense to create a game overview page to create an overview where users can find all your collections. This game overview page can be customized in the same way as the collection page, but will serve as a landing page for your game. -## Creating a game overview page +### Creating a game overview page At this moment in time you can not create a game overview page yourself. If you want to create a game overview page, please request this through the Partner Success Manager or Business Development Lead you're in contact with. You can simply provide them with the following information: - The chain you want to create the game overview page on diff --git a/pages/service/sphere/editor-sections.mdx b/pages/service/sphere/editor-sections.mdx index e8c949c..05a3ee4 100644 --- a/pages/service/sphere/editor-sections.mdx +++ b/pages/service/sphere/editor-sections.mdx @@ -10,7 +10,7 @@ You can view the minimum requirements to create a collection page [here](/servic Sections marked with an asterisk are required to create a collection or game page. -## Header* +### Header* The header section consists of a background image, your logo, stats from your collection and your social links. You're able to adjust both images and your social links. @@ -18,55 +18,55 @@ You're able to adjust both images and your social links. ![Header section](/editor-previews/header.png) -## Introduction text* +### Introduction text* The text in this section is automatically animated by breaking it into smaller chunks at commas and periods. The text has a maximum amount of 300 characters. You can customize your gradient or choose from predefined ones, which will also be applied to the page's scrollbar. ![Introduction text section](/editor-previews/introduction-text.png) -## NFT gallery +### NFT gallery Within this section you can simply enter token id's, we'll automatically fetch the images of all tokens to display them in an animated gallery. You can select up to 20 different token id's. This section is not available within the game editor. We recommend adding your tokens in pairs of 4, since this will result in a consistent grid. ![NFT gallery section](/editor-previews/nft-gallery.png) -## Title and text +### Title and text This section simply consists of a title and some body text, the body text has a maximum length of 200 characters. ![Title and text section](/editor-previews/title-and-text.png) -## Video and image +### Video and image In this section, you can include an image and a video. The video can be a URL or file path, and supports platforms like YouTube, Facebook, Twitch, SoundCloud, Streamable, Vimeo, Wistia, Mixcloud, DailyMotion, and Kaltura. We recommend using an image with dimensions of at least 640 x 768 pixels. ![Video and image section](/editor-previews/video-and-image.png) -## Text and image +### Text and image This section features a full screen background images that gets overlaid with text as it fades away on scroll. We recommend using an image with dimensions of at least 3840 x 2160 pixels for your background image, the maximum amount of characters for the text is 200. ![Text and image section](/editor-previews/text-and-image.png) -## Video +### Video In this section you can simply add a video, just like the video and image section the video can be a URL or file path, and supports platforms like YouTube, Facebook, Twitch, SoundCloud, Streamable, Vimeo, Wistia, Mixcloud, DailyMotion, and Kaltura. ![Video section](/editor-previews/video.png) -## Image collection +### Image collection This section allows you to add three images that feature a subtle parallax effect. Each image can have a caption (this is optional) with a maximum of 50 characters. You can also add a title with a maximum of 50 characters. We suggest using an image with dimensions of at least 880 x 1200 pixels for the first, 512 x 768 pixels for the second, and 660 x 512 pixels for the final image. ![Image collection section](/editor-previews/image-collection.png) -## Text +### Text This section simply consists of text, the text can have a maximum length of 200 characters. ![Text section](/editor-previews/text.png) -## Footer* +### Footer* This is the only section that allows you to create your own CTA button, you can customize the text and the link. The footer section also includes a title and some body text. The maximum amount of characters for the body text is 400 characters. We recommend adding a CTA to your footer to link to your website or social media. diff --git a/pages/service/sphere/introduction.mdx b/pages/service/sphere/introduction.mdx index 73ecd50..713106a 100644 --- a/pages/service/sphere/introduction.mdx +++ b/pages/service/sphere/introduction.mdx @@ -5,11 +5,12 @@ title: Introduction to Sphere # Introduction to Sphere Sphere is the marketplace for games, the backbone of game developers to launch an in-game marketplace. It is the very first marketplace to have ever successfully integrated the Immutable zkEVM testnet and mainnet. Sphere can be used on Beam and Immutable zkEVM. Learn more about the Immutable zkEVM integration and its benefits [here](https://medium.com/@meritcircle/sphere-launches-as-first-marketplace-to-integrate-with-immutable-zkevm-757a565d7f99). -## The only gaming marketplace you will ever need + +### The only gaming marketplace you will ever need As a marketplace, Sphere covers all the bases. First, it acts as an aggregator, presenting a huge range of assets from multiple games that users can search within and browse through — kind of a digital catalog. But Sphere also facilitates in-game marketplaces. Thanks to the [Beam SDK](/service/sdk), anyone who’s building a game has the ability to spin up a marketplace within the game, where players can buy, sell and trade their assets. It all happens under the hood, so it doesn’t disrupt the gamer’s experience, and Sphere collects fees on each transaction. -## Sphere Features +### Sphere Features - **Aggregator**: Sphere acts as an aggregator, presenting a huge range of assets from multiple games that users can search within and browse through. - **Beam SDK**: Thanks to the Beam SDK, anyone who’s building a game has the ability to spin up a marketplace within the game, where players can buy, sell and trade their assets. It all happens under the hood, so it doesn’t disrupt the gamer’s experience, and Sphere collects fees on each transaction. @@ -20,7 +21,7 @@ As a marketplace, Sphere covers all the bases. First, it acts as an aggregator, Go to [Sphere](https://sphere.market/beam) or [Sphere testnet](https://testnet.sphere.market/beam-testnet). -## Learn more +### Learn more - [Sphere Fees](/chain/beam-ecosystem/sphere#are-there-any-fees-associated-with-sphere-transactions) - [Publishing your collection on Sphere](/service/sphere/publish-collections) - [Removing your collection on Sphere](/service/sphere/remove-collections) diff --git a/pages/service/sphere/publish-collections.mdx b/pages/service/sphere/publish-collections.mdx index 983de9a..452c388 100644 --- a/pages/service/sphere/publish-collections.mdx +++ b/pages/service/sphere/publish-collections.mdx @@ -8,7 +8,7 @@ import { Callout } from "nextra/components"; Make your collection stand out on Sphere by adding your personal touch and creating a branded collection page. Before you get started, just follow a few simple steps: -## Mint a token +### Mint a token You'll need to mint at least one token for your collection to be displayed on Sphere. Once you've done that, our system will pick up your collection automatically. After minting at least one token you can check out your collection page at: ```md filename="MAINNET" sphere.market/beam/collections/{contract-address} @@ -17,7 +17,7 @@ sphere.market/beam/collections/{contract-address} testnet.sphere.market/beam-testnet/collections/{contract-address} ``` -## Become a creator +### Become a creator To edit your collection, you need to become a recognized creator on Sphere. Get flagged as a creator by one of our admins (decide which wallet address you would want to use for this and request this through the Partner Success Manager or Business Development Lead you're in contact with), and you'll have the power to edit the collections you've created. Make sure to sign up to Sphere with your desired wallet address before requesting to become a creator. @@ -27,10 +27,10 @@ To edit your collection, you need to become a recognized creator on Sphere. Get -## Edit your collection +### Edit your collection Once you've completed the first two steps, find your collections on the Collections tab of your Sphere account (that matches the wallet address you've sent to our admins). Click on the **Customize Collection** button, and easily make changes using the collection editor. -## Minimum requirements +### Minimum requirements There are a few required fields that need to be filled in before your collection can be published. You'll need to have assets for them before you can publish your collection. These are: - **Name** - **Description**: Max 200 characters for cards, 600 for pages. diff --git a/pages/service/trading/introduction.mdx b/pages/service/trading/introduction.mdx index b162d08..3c40f66 100644 --- a/pages/service/trading/introduction.mdx +++ b/pages/service/trading/introduction.mdx @@ -15,6 +15,5 @@ If you're building a trading based game that doesn't necessarily rely on buying Throughout the coming months, we'll be releasing additional features that will help you provide a more complete marketplace experience, with features ranging from programmatic offers, auctions and extensive filtering options to allow you to create a full-fledged in-game marketplace solely by relying on the Beam marketplace. - Feel like something is missing, and needs to be prioritized? Check out our - [2024 roadmap](/service/roadmap) or let's have a chat through build@onbeam.com + Feel like something is missing, and needs to be prioritized? Let's have a chat through build@onbeam.com! diff --git a/pages/service/transactions/custom-charges.mdx b/pages/service/transactions/custom-charges.mdx index 17054e8..d4e374f 100644 --- a/pages/service/transactions/custom-charges.mdx +++ b/pages/service/transactions/custom-charges.mdx @@ -35,7 +35,7 @@ const transaction = await beam.assetsV2.transferAssetV2("your-sender-id", { // } ``` -### Alternative methods of handling transactionHash +### Alternative methods of handling transactions - [Sponsored transactions](/service/transactions/sponsored-transactions): Learn about sponsored transactions for your users - [Profile-paid transactions](/service/transactions/profile-paid-transactions): Learn about how to make a profile pay for it's own transactions through BEAM diff --git a/pages/service/transactions/introduction.mdx b/pages/service/transactions/introduction.mdx index e57fbaf..9757eb3 100644 --- a/pages/service/transactions/introduction.mdx +++ b/pages/service/transactions/introduction.mdx @@ -6,7 +6,7 @@ title: Transactions Through Profiles, you were able to create a bunch of in-game accounts for your users and your own utility purposes. We've also explained how these in-game accounts can be funded with assets through minting - but before we dive into managing those assets within the profiles, it's good to have a general understanding about transactions. -Within the context of our sdk, a transaction is a transfer of assets of one profile to another - but since our underlying technology is blockchain, a transaction can also simply be explained as any on-chain transaction happening for your profiles (which are account abstractions) +Within the context of our SDK, a transaction is a transfer of assets from one profile to another - but since our underlying technology is blockchain, a transaction can also simply be explained as any on-chain transaction happening for your profiles (which are account abstractions). ### Transactions and gas diff --git a/pages/service/transactions/profile-paid-transactions.mdx b/pages/service/transactions/profile-paid-transactions.mdx index d158a20..9f6350c 100644 --- a/pages/service/transactions/profile-paid-transactions.mdx +++ b/pages/service/transactions/profile-paid-transactions.mdx @@ -4,7 +4,7 @@ title: Profile-paid transactions # Profile-paid transactions -An alternative to the default of sponsoring transactions, is to make the Profile pay for a transaction. This requires the profile to have enough BEAM in its possession to pay for the gas fees needed to handle the network transaction. This generally comes down to a very small sum of BEAM, but if you never distributed any BEAM to the Profiles that you've created, there's a big chance that none of the profiles actually have the required BEAM in place. +An alternative to the default of sponsoring transactions, is to make the Profile pay for a transaction. This requires the profile to have enough BEAM in its possession to pay for gas fees needed to handle the network transaction. This generally comes down to a very small amount of BEAM, but if you never distributed any BEAM to the Profiles that you've created, there's a big chance that none of the profiles actually have the required BEAM in place. In order to mitigate that, you could go different directions. Which is viable to you and your userbase completely depends on your context. @@ -39,7 +39,7 @@ const transaction = await beam.assetsV2.transferAssetV2("your-sender-id", { // } ``` -### Alternative methods of handling transactionHash +### Alternative methods of handling transactions - [Sponsored transactions](/service/transactions/sponsored-transactions): Learn about sponsored transactions for your users - [Custom charges](/service/transactions/custom-charges): A guide to managing and updating your game's assets and details within Beam. diff --git a/pages/service/transactions/sponsored-transactions.mdx b/pages/service/transactions/sponsored-transactions.mdx index ebed3bb..40cb0c7 100644 --- a/pages/service/transactions/sponsored-transactions.mdx +++ b/pages/service/transactions/sponsored-transactions.mdx @@ -8,9 +8,9 @@ By default, all transactions are **sponsored by you**. Sponsoring transactions m ### Why are transactions sponsored by default? -We think this default is sensible, as it's you as the game developer are in control of when a transaction happens. We consider it your responsibility as a game developer to create a viable economic model where sponsored and self-paid transactions (through BEAM or custom charges) go hand in hand to create the best experience for the gamer. +We think this default is sensible, as it's you as the game developer who is in control of when a transaction happens. We consider it your responsibility as a game developer to create a viable economic model where sponsored and self-paid transactions (through BEAM or custom charges) go hand in hand to create the best experience for the gamer. -To paint a clearer picture on how this looks like, below you'll find a transaction which is sponsored +To paint a better picture on how this looks like, below you'll find a transaction which is sponsored ```typescript const transaction = await beam.assetsV2.transferAssetV2("your-sender-id", { @@ -32,7 +32,7 @@ const transaction = await beam.assetsV2.transferAssetV2("your-sender-id", { // } ``` -### Alternative methods of handling transactionHash +### Alternative methods of handling transactions - [Profile-paid transactions](/service/transactions/profile-paid-transactions): Learn about how to make a profile pay for it's own transactions through BEAM - [Custom charges](/service/transactions/custom-charges): A guide to managing and updating your game's assets and details within Beam.