Abstract
Back from the ancient days of human civilization, games were fun! Making money was even more fun! Nowadays, games are still enjoyable, and when games involve betting, they become even more thrilling!
What if we could harness the power of blockchain to ensure transparency in betting games?
It sounds intriguing, but currently, many people are unfamiliar with playing in the decentralized world of blockchain. One of the challenges of web3 applications is onboarding users to the nature of blockchain, which requires a wallet and some gas fees for transactions to be processed on the chain. It can be daunting for newcomers to figure out how to obtain a crypto wallet, provide gas fee coins, and send transactions. PalGam recognizes that to attract the next wave of players, the user experience must closely resemble that of current web2 games. To address this, PalGam simplifies onboarding for players by generating EOA wallets during registration and structuring its base on ERC4337 Account Abstraction. With Account Abstraction, players can pay network gas fees using their USDT balance in smart contract wallets to enter game tables without worrying about having native coins to cover transaction gas fees. PalGam implements gas abstraction on the ERC4337 Account Abstraction infrastructure and selects the USDT ERC20 token on the Polygon PoS chain, ensuring that all transactions in the game are based on the Polygon PoS network.
So, let’s talk more about the AA used in the PalGam:
In accordance with the project's requirements, which involved allowing users to pay transaction fees with Polygon PoS Tether USD (USDT), we had to implement Account Abstraction (ERC-4337) for the core functionalities of the blockchain-related aspects of the PalGam game. Therefore, in the latest version of the game, most functional wallets are smart contract wallets (also referred to as smart accounts), and the user's main wallet is a smart contract wallet.
Smart Accounts
Smart accounts, or smart contract wallets, are smart contracts obtained and controlled by an EOA account signature. They can be considered user accounts with implemented logic. Utilizing them allows for the implementation of gas abstraction and batch transactions.
- In the AA realm, user transactions are not primarily referred to as the main component. Instead, there is something known as a userOperation, which is a pseudo transaction. Once generated, it is sent to the bundler in a userOp's private mempool for verification. Subsequently, it is sent to the EntryPoint contract (currently v6.0), which is a singleton on different chains with a unique contract address. Then, the gas fee for the desired transaction is paid via the user's smart account's USDT (and purchased Matic, as explained below).
- We are actively developing the Biconomy V2 smart account factory contract, which is the latest and recommended account factory by Biconomy.
- Our system utilizes multiple bundlers and paymasters.
When a user wants to play a betting game for the first time, a smart wallet is deployed, and the deployment's gas fee is paid by the user's smart account's USDT. If there is at least $0.5 (in addition to the table bet amount that will be paid for entry) in the user's smart account, it will be automatically converted into Matic. This Matic balance will be used as gas fee for the user's transactions until it decreases. When the Matic balance decreases and the user attempts a transaction, another transaction will be sent to purchase additional Matic for the user. However, if the Matic balance of the user runs out, the gas fee for the user's transaction will be paid in USDT, and another transaction will be sent to convert some USDT to Matic, replenishing the user's gas balance to cover the gas fees for subsequent transactions. If there is not enough USDT to purchase Matics, gas fees will be paid using the remaining USDT balance.
Flow of Deposit Process
As per PalGam's logic, each user is assigned an EOA wallet generated by PalGam, and a smart contract wallet address will be precomputed and shown to them. However, when a user initiates deposits from outside the game application, we are unaware of the individuals attempting to deposit funds into their wallet. Whenever a user wants to enter a game, they have to deposit funds into their smart contract wallet. Therefore, the first time a user joins the game, their smart contract wallet will be deployed on-chain.
There are two different scenarios that could occur when depositing funds into PalGam, which are best understood via the diagram below.
Scenario 1: User has USDT in their wallet on the Polygon PoS chain:
- The user easily initiates a funds transfer transaction from their external wallet to their smart contract wallet within the game.
Scenario 2: User has USDT in a wallet on other chains (besides Polygon PoS):
- The user easily initiates a funds transfer transaction from their external wallet to their smart contract wallet within the game. This process involves interchain bridging, facilitated here by semi-decentralized bridging aggregators.
The user's smart contract wallet is unique and remains with the user permanently on each chain.
The deposit address is precomputed during the user's register, and thereafter, it is stored. When the user wishes to deposit funds into their smart account, the app will display the provided address in QR code format.
Flow of Withdrawal Process
Withdrawals follow a similar process to deposits, with users specifying the chain to which they wish to transfer their funds. However, in this case, we will encounter three scenarios, which are best understood through a diagram provided below.
Scenario 1: The User wants to withdraw to the Polygon PoS chain:
- The user easily initiates a funds transfer transaction from their smart wallet inside the app to their chosen wallet address wherever they desire. In this scenario, gas fees increase by 100%, with 50% of that amount going to the PalGam wallet as the withdrawal commission.
- Additionally, PalGam imposes a general fee of $0.01 for every withdrawal transaction.
Scenario 2: The User wants to withdraw to EVM-based chains other than Polygon PoS and Tron:
- The user initiates a request to withdraw funds from their smart wallet inside the app to their chosen wallet address. This process involves bridging and is facilitated by the decentralized interchain bridging solution, with gas fee deductions falling under one of the cases listed below:
- As a result of this process, a 1% commission is deducted from the total transfer amount for PalGam and the bridging providers.
- Gas fees increase by 100%, with 50% of that amount going to the PalGam wallet.
- Additionally, PalGam imposes a general fee of $0.01 for every withdrawal transaction.
Scenario 3: The User wants to withdraw to the Tron chain:
- The user easily initiates a funds transfer transaction from their smart wallet inside the app to their chosen wallet address. This process involves interchain bridging and is facilitated by semi-decentralized bridging aggregators. Additionally, gas fees increase by 100%, with 50% of that amount going to the PalGam wallet.
During the withdrawal process, gas fees and commissions are deducted from the value being transferred from the user's smart wallet. For example, if the user wants to transfer 100 USDT, by deducting $1 as fees and commissions, the transferred value will be $99. This $1, in the example scenario, will be exchanged for the needed Matic tokens in the user's smart account to cover gas fees for the transaction. Note that a few Matic tokens may remain in the account after the transaction. The withdrawal process described in Scenario 2 is broken down into the following steps:
- First, a message is returned from the bridging provider due to the user's specified withdrawal configurations, which must be signed by the user.
- The swap fee is returned by the bridging provider to determine the amount of native coin (Matic) needed for interchain swapping.
- Using the Uniswap router, the current price of Matic/USDT is retrieved in the source chain (Polygon PoS).
- The retrieved USDT is then transferred from the user's smart account to Uniswap to obtain an amount equivalent amount of Matic in return.
- The equivalent amount of Matic is transferred to the user's smart account.
- Finally, the actual interchain swap occurs.
All of the above steps are executed within the same transaction as part of a batch transaction. Here are the keywords for each step to put in the sequence diagram:
Bet Tables Management System
PalGam generally offers two types of games: Free and Bet. In free games, there are no on-chain transactions, as these games operate similarly to normal web2 games. Free game tables allow players to enter the game without needing any funds. These types of tables do not include any commission, and consequently, there are no winnings for the table winner.
Further exploration of the games reveals various types of non-free tables. Here is the current list of bet tables:
- 1-to-1 Betting Table
- Tournament
For 1-to-1 betting tables, players can play with their friends or with random opponents. In friendly tables, players can choose the bet amount themselves.
In bet tables, due to the block gas limits and desired speed for joining players to the game, two strategies have been devised:
1. Pre-generated bet table contracts: These contracts are cloned from the main implementation. These pre-generated table contract instances are ready to be used by joining players and isolate the bet amount in that specific contract for each game.
2. Session-based user unlocking: The only contract in PalGam considered for placing bets or transferring USDTs to the bet tables is the Bet Table Factory smart contract. Players can approve the address of the Bet Table Factory for high values and be assured that the Bet Table Factory cannot transfer any money from their USDT account until their session is locked. Players can unlock or lock their session whenever they want. This feature allows players to experience a faster and more secure game joining process without needing to approve every time they want to join a bet table. (Players who play with their bonus balance do not need to approve or unlock sessions.) Players must approve the PalGam Bet Table Factory contract and call the unlock session function to unlock their session for the desired duration, after which they will be able to join any bet table listed above.
Approval amount: When a user is about to play a betting game for the first time, token approval will be obtained from the user for 10 times the bet amount of the table. However, if the resulting amount is less than $50, approval will be obtained for $50. For example, if the user wants to play a game with a $1 bet amount, the approval amount will be $50 (10 times more than $1, but less than $50). In another case, if the bet amount is $10, the user will approve $100, which is 10 times more than $10.
1-to-1 Betting Games Process
Joining Players: Player A requests to join a pre-defined game table, for example, a $10 table. Player A then waits for the game to find and match another user, let's say Player B, with the same request. The app selects an empty game table, and the bet table admin calls the join function, adding both players to the bet table. Through this process, their funds are transferred to that specific bet table, and table parameters are set, allowing both players to sit at the bet table. It's important to note that at most one of the players can play with their bonus balance.
Determining the Winner: Based on the game result, the winner is selected by the app. It's notable that if one of the players leaves the game voluntarily, gets disconnected from the internet, or runs out of time, the player who stays in the game longer will be declared the winner. After determining the winner, payments are made, and table parameters are reset. Payments include:
- Commission for PalGam (and the winner’s referrer if one exists)
- Gas costs of the table
- Winner’s winning amount
Commission: Upon announcing the winner, the commission is transferred to the PalGam commission wallet. If the player has a referrer (and is not playing with a bonus balance), a portion of this commission will be transferred to the referrer's account. The default PalGam commission is 3%, but it can range between 2% and 10%. example, in a $10 bet table with a 3% commission percentage for PalGam, the total commission would be $0.3. If the winner has a referrer and the referrer's commission percentage is 25%, the PalGam commission would be $0.225, and the referrer's commission would be $0.075. Note that if one of the players is playing with their bonus balance, the PalGam commission will be transferred to the bonus pool.
Gas Costs: The amount of gas consumed for executing the joining transaction and setting the winner transaction is stored in the bet table. After the game finishes, considering the gas price and gas ratio, the total gas cost of the game is deducted from the table balance and sent to PalGam's gas wallet. The gas ratio is a value that is set to multiply the gas price from the app side to expedite transactions and increase the speed of joining players or other function calls for the table. The default gas ratio is 1.6 and can range between 1 and 2.
Winning Amount: If the winner is playing with their main balance, the remaining balance in the table is transferred to the winner’s smart account. If the winner is playing with their bonus balance, the winning amount is transferred to their bonus account.
Refunding Process: In the event of any issues arising during the game processes, where players’ funds remain locked in the table and there is no option to complete the game due to unforeseen circumstances, players have the ability to initiate a refund. This refund request can be made two days after their initial joining time. This policy ensures that players are not left without recourse in situations beyond their control, providing a fair and transparent mechanism for reclaiming their tokens.
Tournaments Process
PalGam offers tournaments for each game, facilitated by the Tournament Management System, empowering admins to create new tournaments and define essential parameters for each game. During tournaments, participants are randomly selected, and those progressing to subsequent rounds carry forward any remaining funds from the previous stage. Entry fees are debited from players' main balances upon tournament registration, with a platform commission of 10% levied on the total value of tournament matches. The process is as follows:
Setting the tournament data: The tournament admin sets tournament-related parameters such as entry fee, required players, start time (if applicable), etc. Then, a tournament contract instance is ready to join players to it. Each tournament operates within its own isolated smart contract clone, ensuring the secure collection of entry bet amounts. Additionally, tournaments can be initiated without a specified start time, allowing PalGam to use them as small or anytime runnable tournaments. The only criterion for starting such tournaments is the presence of the required number of players.
Joining players: Players can participate in the tournament by submitting a request within the app, and PalGam will facilitate their addition by invoking the designated function. The tournament admin calls the function to join players to the tournament instance. This function can be executed multiple times until the required number of players is reached. The Tournament Admin has the ability to utilize the designated join function to include multiple players in a specific tournament. During this process, the entry fee is deducted from the players' main balances and transferred to the specific smart contract associated with the tournament. It's important to note that this function is only available for open tournaments and can be executed until 3 hours before the set start time (if specified). Within this timeframe, only the required number of players can join to ensure the tournament progresses smoothly.
Finishing the tournament: After the tournament has concluded, the Tournament Admin can call the function to specify the winners' addresses. During this process, PalGam distributes its commission and winners' prizes. As mentioned before, PalGam's commission for tournaments is 10%. The prize distributions vary depending on the game type:
- For 1-to-1 betting games: The top three players receive prizes of 65%, 15%, and 10% of the total tournament pot.
It's important to note that all these percentages, including the PalGam commission and winners' prize allocations, are fixed and hardcoded. All gas costs incurred during the entire tournament, including all function calls mentioned earlier, are covered by PalGam. Players are not responsible for paying any gas fees used in tournament function calls.
Multi-Confirmation for Finishing the Tournament: For security reasons, a strategy is applied for tournaments with a prize pool exceeding $1000. In these cases, when the tournament admin calls the designated function to finish the tournament, the top players will be stored in the contract, and the first confirmation will be done. However, the payments will remain pending until the tournament finisher admin calls the confirm finish function. After this, all payments, including PalGam commission and top players' prizes, will be distributed.
At the end of the process, the parameters of the tournament contract will be reset.
Refunding Process: In the event of any issues arising during tournament processes, where players’ funds remain locked and there is no option to complete the tournament due to unforeseen circumstances, players have the ability to initiate a refund. This refund request can be made up to 30 days after the tournament's start time. This policy ensures that players are not left without recourse in situations beyond their control, providing a fair and transparent mechanism for reclaiming their tokens.
Bonus Management System
In PalGam, players have the opportunity to receive bonuses under various circumstances, such as completing 20 free bet plays, registering in the app using a referral code, or on certain occasions. The PalGam Bonus Admin is responsible for distributing bonuses to players, either manually or automatically (e.g., registering with a referral code). It's important to note that each type of bonus can be set as active or deactivated. For instance, if the referral bonus is deactivated, users who register with a referral code will no longer receive that specific bonus. Once a user receives a bonus, it cannot be canceled, and PalGam cannot retract bonuses that have already been distributed. While the PalGam Referral Admin can enable or disable bonus distribution, they cannot revoke or halt distributed bonuses.
In cases where a player receives multiple bonuses within the same time period, the newer bonus will be queued until the fate of the older bonuses is determined. Bonus balances are kept separate from players' main balances, with each bonus valued at $1. Players have a two-week deadline to utilize their bonus balance. If their bonus balance falls below $1, the bonus will be lost. Players can use bonuses to participate in 1-to-1 betting tables, and if a player's total bet plays with bonuses exceed $100 during that two-week period, their bonus balance will be automatically transferred to their main balance. However, if the two-week period elapses, players will lose their bonus balance.
The Bonus Pool smart contract manages the balance of distributed bonuses. PalGam can transfer tokens to this smart contract address, effectively creating the PalGam bonus distribution pool. When a user receives a bonus, their balance is updated within this contract. Admins have the ability to withdraw non-active bonus balances from this smart contract, which includes tokens that are not allocated to bonuses. Additionally, PalGam can withdraw the amounts related to bonuses that were issued but not activated during their two-week period. This means that if some users receive bonuses but do not utilize them, PalGam is able to reclaim the corresponding tokens for those non-activated bonuses.
Each player within the application can view the bonuses they have received and use them to enter games. When a player chooses to play with their bonus, the corresponding amount is deducted from the bonus pool (by updating their bonus balance) and transferred to the game table. If a player with a bonus wins, the amount is transferred to the bonus pool, and their bonus balance will be updated, while if their opponent wins, the amount is transferred from the game bet table to that player’s main balance. It's important to note that two players with bonuses cannot play against each other; one of them must enter the game using their main balance at least. Additionally, players cannot use their bonus balance in friendly games, or to entering tournaments. The PalGam commission earned from games involving a player with a bonus is transferred to the Bonus Pool contract rather than the PalGam commission wallet.
Referral Management System
Each user within the app is assigned referral codes, which they can share with others. When others enter the app using their referral code, they become subset users for that referrer. Essentially, upon registering, each user's referrer address is set in the Referral Pool smart contract. Referrers are referred to as PalGam partners and can earn profits by receiving a specific commission percentage from their subsets' winning bets. The initial commission percentage for partners is set at 25%. This means that when their subsets win, 25% of PalGam's commission from that game is transferred to the referral balance of the referrer of the winner. In simpler terms, 25% of the app's profit from that particular game is allocated to that partner's referral balance. The accumulated referral balance is stored within the Referral Pool contract. It's important to note that subsets playing with a bonus balance are not counted for referral commission payments.
Users can view the individuals who have joined the app using their referral code in the "Subsets" section. Partners cannot transfer their referral balance to their main balance until the following conditions are met:
- A minimum of 5 registrations using their referral code.
- Each subset must win at least 1 bet game.
- The total bet winnings of all subset players must reach $1,000.
The withdrawal limit for the accumulated amount in the referral balance is set at a minimum of $2. Partners can request to withdraw their referral balance, which can be initiated by the PalGam Referral Admin or by the users themselves, allowing for independent action. Please note that the gas cost for this transaction will be deducted from the withdrawal amount. It is important to emphasize that PalGam does not have access to withdraw any funds from the Referral Pool contract.
If the total winnings of a player's subsets reach $100,000, their commission percentage increases from 25% to 30%. If it reaches $200,000, it increases to 35%, and if it reaches $500,000, it further increases to 45%.
PalGam admin has the authority to adjust the partner commission percentage within the range of 25% to 45%. However, once a partner meets the criteria to increase their commission percentage, as mentioned previously, PalGam admin cannot set their commission percentage to a value lower than the valid floor.