chore: policy documentation (#106)

* chore: document policies

* chore: restore chain docs

* chore: formatting

* chore: restore terms of service

* chore: restore chain docs

* chore: adjust policy documentation

* chore: adjust policy documentation

* chore: adjust policy documentation

* Updated understanding-policies.mdx for added clarity

* added more detail on how each of the policies work

* Change gold to diamond for consistency

* Fix typo

---------

Co-authored-by: alejandroreinel <[email protected]>
Co-authored-by: areinel <[email protected]>
Co-authored-by: lewinskimaciej <[email protected]>

components/network-button/network-button.tsx

@@ -1,27 +1,27 @@
-import { Button } from 'nextra/components';
+import { Button } from "nextra/components";
 
 const NETWORK_PARAMS = {
   13337: {
-    chainId: '0x3419',
-    chainName: 'Beam Testnet',
+    chainId: "0x3419",
+    chainName: "Beam Testnet",
     nativeCurrency: {
-      name: 'Beam,',
-      symbol: 'BEAM',
+      name: "Beam,",
+      symbol: "BEAM",
       decimals: 18,
     },
-    rpcUrls: ['https://subnets.avax.network/beam/testnet/rpc'],
-    blockExplorerUrls: ['https://subnets-test.avax.network/beam'],
+    rpcUrls: ["https://subnets.avax.network/beam/testnet/rpc"],
+    blockExplorerUrls: ["https://subnets-test.avax.network/beam"],
   },
   4337: {
-    chainId: '0x10f1',
-    chainName: 'Beam',
+    chainId: "0x10f1",
+    chainName: "Beam",
     nativeCurrency: {
-      name: 'Beam',
-      symbol: 'BEAM',
+      name: "Beam",
+      symbol: "BEAM",
       decimals: 18,
     },
-    rpcUrls: ['https://subnets.avax.network/beam/mainnet/rpc'],
-    blockExplorerUrls: ['https://subnets.avax.network/beam'],
+    rpcUrls: ["https://subnets.avax.network/beam/mainnet/rpc"],
+    blockExplorerUrls: ["https://subnets.avax.network/beam"],
   },
 };
 
@@ -34,7 +34,7 @@ function NetworkButton({ chainId, label }) {
       try {
         // switch network
         await ethereum.request({
-          method: 'wallet_switchEthereumChain',
+          method: "wallet_switchEthereumChain",
           params: [
             {
               chainId: NETWORK_PARAMS[chainId].chainId,
@@ -46,18 +46,18 @@ function NetworkButton({ chainId, label }) {
           // add network
           try {
             await ethereum.request({
-              method: 'wallet_addEthereumChain',
+              method: "wallet_addEthereumChain",
               params: [NETWORK_PARAMS[chainId]],
             });
           } catch (addError) {
-            console.error('Error adding wallet network', addError);
+            console.error("Error adding wallet network", addError);
           }
         } else {
-          console.error('Error switching wallet network', switchError);
+          console.error("Error switching wallet network", switchError);
         }
       }
     } else {
-      console.error('No injected wallet provider detected');
+      console.error("No injected wallet provider detected");
     }
   }
 

pages/index.mdx

@@ -37,13 +37,17 @@ Unlock the full potential of Beam in your games with our comprehensive APIs and
 
 - [Transactions](/service/transactions): Understand how to run sponsored, self-paid and custom charge transactions.
 
-- [Assets](/service/assets): Simplify in-game asset management
+- [Policies](/service/policies/introduction): Understanding and creating policies.
 
-- [Exchange](/service/exchange/converting-tokens): Convert tokens based on configured liquidity pools
+- [Assets](/service/assets): Simplify in-game asset management.
 
-- [Marketplace](/service/marketplace/introduction): List, buy and make offers on other peoples assets
+- [Exchange](/service/exchange/converting-tokens): Convert tokens based on configured liquidity pools.
 
-- [Companion](/service/companion/introduction): Implement the Beam Companion app in your game
+- [Marketplace](/service/marketplace/introduction): List, buy and make offers on other peoples assets.
+
+- [Companion](/service/companion/introduction): Implement the Beam Companion app in your game.
+
+- [Reporting](/service/reporting): Get some insight on how your game is doing in terms of on-chain transactons
 
 ## Explore the Chain: Your Comprehensive Guide to Beam
 

pages/service/_meta.json

@@ -13,6 +13,9 @@
   "transactions": {
     "title": "Transactions"
   },
+  "policies": {
+    "title": "Policies"
+  },
   "assets": {
     "title": "Assets"
   },

pages/service/policies/_meta.json

@@ -0,0 +1,6 @@
+{
+  "introduction": "Introduction",
+  "understanding-policies": "Understanding policies",
+  "managing-policies": "Managing policies",
+  "using-policies": "Using policies"
+}

pages/service/policies/introduction.mdx

@@ -0,0 +1,11 @@
+# Policies
+
+Policies are the means to make Profiles pay for transactions in an on-chain, in-game ERC20 token - but not necessarily the native one. If your game supports an in-game ERC20 token - let's call them Gold - and you would like to charge your user an X amount of Gold for every on-chain transaction you facilitate, Policies are the feature you're looking for.
+
+A policy is nothing else than a simple set of rules, which you can reference in every transaction that you make - the rules you define are up to you.
+
+- [Understanding policies](/service/policies/understanding-policies): Explainer on the different types of policies
+
+- [Managing policies](/service/policies/managing-policies): How to create, retrieve and delete policies
+
+- [Using policies](/service/policies/using-policies): How to use the policies you defined

pages/service/policies/managing-policies.mdx

@@ -0,0 +1,52 @@
+# Creating policies
+
+Creating a policy is as simple as calling the `CreatePolicy` method. We highly recommend getting a good understanding about policies first by reading the [Understanding policies](/service/policies/understanding-policies) section.
+
+```typescript
+const profile = await beam.policies.createPolicy({
+  tokenAddress: "0x0...", // ERC20 token address (contract must be added to your game)
+  amount: 1, // the fixed charge or the exchnage rate to wei
+  rateType: "Fixed", // 'Fixed' (recommended) or 'Dynamic'
+  chainId: 13337, // 13337 for Beam testnet, 4337 for mainnet
+});
+
+// {
+//   "id": "string",
+//   "chainId": 13337,
+//   "token": "string",
+//   "amount": "string",
+//   "rateType": "Fixed"
+// }
+```
+
+#### Retrieving all policies
+
+If you want to return a list of all active policies in your application use the `GetPolicies` method.
+
+```typescript
+const profile = await beam.policies.getPolicies();
+
+// {
+//   "data": [
+//     {
+//      "id": "string",
+//      "chainId": 13337,
+//      "token": "string",
+//      "amount": "string",
+//      "rateType": "Fixed"
+//     }
+//   ]
+// }
+```
+
+#### Deleting policies
+
+If you want to clean up old policies, simply call the `DeletePolicy` method and pass the Policy ID.
+
+```typescript
+const profile = await beam.policies.deletePolicy("policy-id");
+
+// {
+//   "success": true,
+// }
+```

pages/service/policies/understanding-policies.mdx

@@ -0,0 +1,36 @@
+## Understanding Gas and Policies in EVM Blockchains
+
+### Overview of Gas on EVM Blockchains
+- **Gas Units**: A measure of computational effort required to execute transactions or smart contracts on the Ethereum Virtual Machine (EVM).
+- **Gas Payment in Native Currency**: Each blockchain has its own native currency for gas payments. Examples include:
+- Beam: Paid in Beam.
+- Ethereum: Paid in Ether.
+- Polygon: Paid in MATIC.
+
+### Challenge: Users Lacking Native Currency
+In scenarios where users need to transact but lack the native currency for gas, Beam 'policies' provide a solution, allowing for payments in a specific ERC20 token.
+
+### Types of Policies for Transactions
+
+#### 1. Fixed Charge Policies
+**A set amount of the ERC20 token is charged per transaction, regardless of the gas cost.**
+- **Economics**: While offering stable and predictable costs for users, this model can be financially risky for developers during high gas prices.
+- **User**: Users benefit from a straightforward and predictable cost structure, making budgeting for transactions easier and transparent.
+- **Example**: A transfer transaction might be set at 1 $Gold, while a minting transaction costs 10 $Gold. They will always cost the same, regardless of the gas price.
+
+#### 2. Dynamic Charge Policies
+**Charges in ERC20 tokens are calculated based on the current gas cost, the developer needs to set and exchange rate of ERC20 to wei in native currency.**
+- **Economics**: Aligns transaction costs with real-time gas market prices, introducing variability in costs for the user.
+- **User**: Users face fluctuating transaction costs, which can be challenging to predict and may require an understanding of gas market dynamics.
+- **Example**:
+- If the gas price is 20 gwei:
+- Mint transaction: 100 gas units * 20 gwei = 2,000 wei (equivalent to 20,000 $Gold at an exchange rate of 10 $Gold per wei).
+- Transfer transaction: 50 gas units * 20 gwei = 1,000 wei (equivalent to 10,000 $Gold).
+- If the gas price is 10 gwei:
+- Mint transaction: 100 gas units * 10 gwei = 1,000 wei (equivalent to 10,000 $Gold).
+- Transfer transaction: 50 gas units * 10 gwei = 500 wei (equivalent to 5,000 $Gold).
+- **Note**: Example calculations are for illustrative purposes and should be adapted for production use.
+
+### Choosing Between Fixed and Dynamic Policies
+Developers must weigh the benefits of simplicity (fixed policies) against the need for adaptability to market conditions (dynamic policies).
+- **User Considerations**: Given that most users lack in-depth knowledge of gas mechanics, the responsibility of managing price volatility and associated risks ideally lies with the developers.

pages/service/policies/using-policies.mdx

@@ -0,0 +1,20 @@
+# Using policies
+
+Once created, policies will only be used if you explicitly pass the Policy ID when running a transaction. The general rule of thumb is that the `policyId` property will be available on every method in our SDK if the method itself triggers an on-chain transaction.
+
+```typescript
+const transaction = await beam.assets.transferAsset("your-sender-id", {
+  receiverEntityId: "your-receiver-id",
+  assetAddress: "your-contract-address",
+  assetId: "73",
+  // ...
+  sponsor: false, // 👈 This handles the transaction to be self paid
+  policyId: "cl..", // 👈 This triggers the custom policy to be used
+});
+```
+
+---
+
+## Reporting
+
+If you're interesting in getting insight into how each policy is performing in your game, head over to [Reporting](/service/reporting)

pages/service/transactions/custom-charges.mdx

@@ -4,15 +4,15 @@ title: Custom charges
 
 ### Custom charges of in-game currencies (coming soon)
 
-Another — and probably the most interesting option for most developers - is charging in-game (ERC20) tokens as a form of payment for transactions. To easily explain the flexibility this gives you, let's assume you have an in-game token called 'Diamonds'. Users obtain these diamonds either through playing your game, or by making an in-app purchase, and you would like to charge users their Diamonds when you handle a transaction for them.
+Another — and probably the most interesting option for most developers - is charging in-game (ERC20) tokens as a form of payment for transactions. To easily explain the flexibility this gives you, let's assume you have an in-game token called 'Gold'. Users obtain Gold either through playing your game, or by making an in-app purchase, and you would like to charge users their Gold when you handle a transaction for them.
 
 ### Creating a custom charge policy
 
-You could charge your users an X amount of diamonds by simply creating a policy, and providing the `policyId` any transaction. When this happens, the in-game diamond(s) will be taken away from the user, while under the hood we use BEAM to run a transaction.
+You could charge your users an X amount of Gold by simply creating a policy, and providing the `policyId` any transaction. When this happens, the in-game Gold will be taken away from the user, while under the hood we use BEAM to run a transaction.
 
 ### Economic viability
 
-Eventually, you as a game developer will be responsible for funding the BEAM for all the transactions that are ran through our service, so if you take away in-game diamonds, you have to consider if it is economically viable to make this transaction. Let's assume a single transaction on Beam costs < 0.001 BEAM, and a diamond costs the user $ 0.05 to obtain - this means that the transaction through the policy is now not only economically viable, it also allows you to to sponsor quite some transactions for the user as the single diamond paid for the transaction in tenfold.
+Eventually, you as a game developer will be responsible for funding the BEAM for all the transactions that are ran through our service, so if you take away in-game Gold, you have to consider if it is economically viable to make this transaction. Let's assume a single transaction on Beam costs < 0.001 BEAM, and a Gold costs the user $ 0.05 to obtain - this means that the transaction through the policy is now not only economically viable, it also allows you to to sponsor quite some transactions for the user as the single Gold paid for the transaction in tenfold.
 
 ```typescript
 const transaction = await beam.assets.transferAsset("your-sender-id", {