feat: add megafuel doc

docs/bnb-smart-chain/developers/paymaster/Integrated-approach.md

@@ -0,0 +1,78 @@
+# Integrated Approach
+
+This guide outlines the steps for developers to integrate MegaFuel, enabling gas fee sponsorship for their users.   This permissionless solution is open to all wallets/cex/dapp
+
+## Paymaster Endpoint
+
+> 📘 Supported on both BNB Smart Chain and OpBNB.
+
+Endpoint
+
+- BNB Smart Chain (BSC)
+  - **Mainnet**: `https://bsc-megafuel.nodereal.io/`
+  - **Testnet**: `https://bsc-megafuel-testnet.nodereal.io/`
+
+- opBNB
+  - **Mainnet**: `https://opbnb-megafuel.nodereal.io/`
+  - **Testnet**: `https://opbnb-megafuel-testnet.nodereal.io/`
+
+## Example Client Code
+
+This [repository](https://github.com/node-real/megafuel-client-example) contains a series of code examples demonstrating MegaFuel integration across multiple scenarios, including wallet integration and payment gateway integration. The codebase is implemented in both Golang and JavaScript.
+
+## Interaction Workflow
+
+![](https://files.readme.io/30618a1-image.png)
+
+Integration requires adapting the transaction flow to work with MegaFuel's paymaster system. For detailed information about the paymaster API interface, please refer to [this document](https://docs.nodereal.io/reference/eth-sendrawtransaction-megafuel).
+
+The main steps are:
+
+1. **Transaction Preparation**:
+   - When a user initiates a transaction, first call `pm_sponsorable` to check if it's eligible for sponsorship.
+   - If sponsorable, set the transaction's gas price to zero.
+2. **User Notification**:
+   - Inform the user that the transaction will be gas-free and sponsored by the "sponsor name" returned by the API.
+3. **Transaction Signing**:
+   - Have the user sign the zero-gas-price transaction.
+4. **Submission to MegaFuel**:
+   - Send the signed transaction to the MegaFuel through `eth_sendRawTransaction` API.
+   - When making the **eth_sendRawTransaction** request, please set the "User-Agent" header to the wallet application's name. This practice helps MegaFuel better understand usage patterns and improve services. For example -H “User-Agent: your-wallet-name/v1.0.0”. [Example code](https://github.com/node-real/megafuel-js-sdk/blob/main/src/paymasterclient.ts#L116) for reference.
+5. **Response Handling**:
+   - Process the paymaster's response:
+     - If successful, inform the user that the transaction is submitted.
+     - If failed, consider falling back to normal transaction processing or inform the user of the failure.
+6. **Transaction Monitoring**:
+   - Monitor the transaction status as usual.
+
+## Best Practice
+
+1. Always check sponsorability before setting gas price to zero.
+2. Provide clear information to user about who sponsor the tx.
+3. Implement fallback mechanisms for sponsorship failures.
+4. Consider fallback mechanisms for non-sponsored transactions.
+
+## Q&A
+
+1. What are the odds of the **eth_sendRawTransaction** call failing after **pm_sponsorable** returns is_sponsorable: true?
+
+   **Answer**: For wallet retail users, the failure probability is minimal.  
+   There are two main potential failure scenarios:
+
+   - A timing issue where sponsor funds are available during the **pm_sponsorable** check but depleted when **eth_sendRawTransaction** executes.
+   - Nonce mismatch errors, since the **pm_sponsorable** API doesn't include a nonce field, but **eth_sendRawTransaction** API will check nonce. To prevent this, we recommend fetching the correct nonce via [MegaFuel's API ](https://docs.nodereal.io/reference/eth-gettransactioncount-megafuel)endpoint when constructing gasless transactions.
+
+2. Which specific errors or error codes from **pm_sponsorable** and **eth_sendRawTransaction** indicate that we should retry the sponsorable transaction? 
+
+   **Answer**: 
+
+   - The **pm_sponsorable** API serves as a validator for gasless transaction eligibility. Any negative(false) response  or error from this API should trigger an immediate fallback to standard transaction processing.
+   - When **eth_sendRawTransaction** returns nonce-related errors ("nonce too high" or "nonce too low"), retries are appropriate as these issues are typically timing-related and may resolve after a brief delay when the correct nonce becomes available. However, all other error types indicate non-recoverable issues that won't be resolved through retries.
+
+3. Is there a recommended practice for handling fallback scenarios when sending a sponsorable transaction fails?
+
+   **Answer**:  It is suggested to show the error msg and automatically retry every subsequent transaction as a non-sponsored transaction without informing the user.  
+   There are two cases indicate that the gasless paymaster may not work: 
+
+   - The **eth_sendRawTransaction** API return error; 
+   - The **eth_sendRawTransaction** does not return an error, but the tx does not confirm on chain for a long time. A user can consider a gasless transaction failed if it hasn't been mined on BSC network within 120 seconds of submission or 42 seconds on opBNB network. A more precise method to fetch transaction status is to query [MegaFuel API](https://docs.nodereal.io/reference/eth-getgaslesstransactionbyhash).

docs/bnb-smart-chain/developers/paymaster/Sponsor-Guidelines.md

@@ -0,0 +1,201 @@
+# Sponsor Guidelines
+
+## Introduction
+
+Any registered user of Nodereal can become a gas sponsor on the MegaFuel. It empowers users to create and manage their own gas sponsorship, known as sponsor policies. This guide outlines the sponsor registration process and provides instructions for effective utilization of  MegaFuel.
+
+_Note: At present, during the beta phase, policies can only be created by the system after a sponsor initiates an application._
+
+## Registration Process
+
+### Become a MegaNode User
+
+1. Go to <https://nodereal.io/meganode>
+2. Navigate to the login page and select the "Login with GitHub" option.
+<div align="center">
+  <img src="https://files.readme.io/2bb4318-Screenshot_2024-08-14_at_12.34.56.png" width="400">
+  <br>
+</div>
+
+
+3. Choose to create an API key, input a key name and notes, then click "save".
+<div align="center">
+  <img src="https://files.readme.io/b67fe92-cc_2024-08-14T04_29_51.856Z.png" width="400">
+  <br>
+</div>
+
+4. Now you have your first API key, which will be used later to manage policy.
+<div align="center">
+  <img src="https://files.readme.io/70cd000-image.png" width="400">
+  <br>
+</div>
+
+
+5. Click the API Key row to access the key details.
+
+<div align="center">
+  <img src="https://files.readme.io/6c04347-image_1.png" width="400">
+  <br>
+</div>
+
+
+Never share the API key to others and keep it secret. If the API key is leaked, others might be able to manage the paymaster policies.
+
+### Applying to Become a Sponsor
+
+1. Visit the [google form](https://forms.gle/WKb6vnnqvTFYERPE7)
+2. Complete the application form, ensuring you enter the email address associated with your Meganode account.
+
+### Review Process
+
+1. The team will review application within 2-3 business days.
+2. Upon approval, your sponsorship policies will be created and you'll receive a confirmation email with further instructions.
+
+## Testing Your Policy on Testnet
+
+Upon approval, you will receive **two sponsor policies**:
+
+- **Testnet Policy:** Pre-funded with **10 BNB** for system integration testing.
+- **Mainnet Policy:** Requires sponsor funding before being actually used.
+
+## Funding Process
+
+After completing system integration testing, fund your **Mainnet policy** by following these steps:
+
+### 1. Send Sponsorship Funds
+
+- **MegaFuel Receiver Address:**  
+  `bnb:0x855bcfFbDcD35c52EAD99609f5e7ABE211EB4e88`
+- **Sending Address:**  
+  - Provide your sending wallet address in above [application form](https://forms.gle/WKb6vnnqvTFYERPE7).
+  - This will be used to verify deposits and set the maximum gas limit for your policy.
+
+### 2. Notify Us
+
+Once funds are transferred, send the **transaction hash (TX hash)** for verification.
+
+**Contact Information:**  
+
+- **Telegram:** [@ruojunm](https://t.me/ruojunm) or [@constbh](https://t.me/constbh)  
+- **Email:** [[email protected]](mailto:[email protected])    
+
+## Managing Your Sponsor Policy
+
+Once the sponsor policy is created, sponsor will received a sponsor policy UUID. Sponsor can manage the policy through API according to the UUID.
+
+### Add account to the policy whitelists
+
+See API Reference [pm\_addToWhitelist](https://docs.nodereal.io/reference/pm-addtowhitelist)
+
+Here are some example:
+
+- Add "From addresses" into whitelist, only transactions originating from addresses included in this predefined whitelist will be eligible for gas fee sponsorship.
+
+```plain
+curl --location 'https://open-platform-ap.nodereal.io/{$apikey}/megafuel' \
+--header 'Content-Type: application/json' \
+--data '{
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "pm_addToWhitelist",
+    "params": [
+        {
+            "policyUuid": "a2bb7201-a665-4d85-9d6b-860ca5e40e5b",
+            "whitelistType": "FromAccountWhitelist",
+            "values": ["0xBbE8831B3355cDca061B9491f48D39481449991d", "0xeD24FC36d5Ee211Ea25A80239Fb8C4Cfd80f12Ee"]
+        }
+    ]
+}'
+```
+```
+curl --location 'https://open-platform-ap.nodereal.io/{$apikey}/megafuel' \
+--header 'Content-Type: application/json' \
+--data '{
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "pm_addToWhitelist",
+    "params": [
+        {
+            "policyUuid": "a2bb7201-a665-4d85-9d6b-860ca5e40e5b",
+            "whitelistType": "FromAccountWhitelist",
+            "values": ["0xBbE8831B3355cDca061B9491f48D39481449991d", "0xeD24FC36d5Ee211Ea25A80239Fb8C4Cfd80f12Ee"]
+        }
+    ]
+}'
+```
+
+- Add "To addresses" into whitelist, this whitelist restricts the smart contract addresses that sponsored transactions can interact with.
+
+```plain
+curl --location 'https://open-platform-ap.nodereal.io/{$apikey}/megafuel' \
+--header 'Content-Type: application/json' \
+--data '{
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "pm_addToWhitelist",
+    "params": [
+        {
+            "policyUuid": "a2bb7201-a665-4d85-9d6b-860ca5e40e5b",
+            "whitelistType": "ToAccountWhitelist",
+            "values": ["0xBbE8831B3355cDca061B9491f48D39481449991d", "0xeD24FC36d5Ee211Ea25A80239Fb8C4Cfd80f12Ee"]
+        }
+    ]
+}'
+```
+
+- Add "ContractMethodSig" into whitelist, this whitelist restricts the contract methods that sponsored transactions can call.
+
+```plain
+curl --location 'https://open-platform-ap.nodereal.io/{$apikey}/megafuel' \
+--header 'Content-Type: application/json' \
+--data '{
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "pm_addToWhitelist",
+    "params": [
+        {
+            "policyUuid": "a2bb7201-a665-4d85-9d6b-860ca5e40e5b",
+            "whitelistType": "ContractMethodSigWhitelist",
+            "values": ["0xa9059cbb"]     // method signatures, e.g. 0xa9059cbb means "transfer"
+        }
+    ]
+}'
+```
+
+- Add "BEP20Receivers" into whitelist, this whitelist restricts the token receiver addresses for sponsored transactions when the contract is ERC20 transfer.
+
+```plain
+curl --location 'https://open-platform-ap.nodereal.io/{$apikey}/megafuel' \
+--header 'Content-Type: application/json' \
+--data '{
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "pm_addToWhitelist",
+    "params": [
+        {
+            "policyUuid": "a2bb7201-a665-4d85-9d6b-860ca5e40e5b",
+            "whitelistType": "BEP20ReceiverWhiteList",
+            "values": ["0xBbE8831B3355cDca061B9491f48D39481449991d", "0xeD24FC36d5Ee211Ea25A80239Fb8C4Cfd80f12Ee"]
+        }
+    ]
+}'
+```
+
+### Remove items from  policy whitelists
+
+See API Reference [pm\_rmFromWhitelist](https://docs.nodereal.io/reference/pm-rmfromwhitelist)
+
+### Empty the policy whitelists
+
+See API Reference [pm\_emptyWhitelist](https://docs.nodereal.io/reference/pm-emptywhitelist)
+
+### List policy whitelists
+
+See API Reference [pm\_getWhitelist](https://docs.nodereal.io/reference/pm-getwhitelist)
+
+### Upcoming Features...
+
+- Accessing the Console
+- Viewing Existing Policies
+- Modifying Policy Rules
+- Monitoring Sponsorship Activity