diff --git a/docs/bnb-greenfield/for-developers/data-archive/block-archiver.md b/docs/bnb-greenfield/for-developers/data-archive/block-archiver.md index 36875d2e21..670fbf93df 100644 --- a/docs/bnb-greenfield/for-developers/data-archive/block-archiver.md +++ b/docs/bnb-greenfield/for-developers/data-archive/block-archiver.md @@ -36,7 +36,7 @@ conducts validation checks against data already stored in Greenfield, and detect Node operators requiring full sync from the genesis block need access to historical block data via the Block-Archiver. Leveraging Greenfield's robust infrastructure, they can trust the integrity and availability of the stored data. -The Greenfield community has launched the `Greenfield Peer`, a data-seed solution for those who need to run BSC nodes in fullsync mode. For more details, check out this [page](../greenfield-peer). +The Greenfield community has launched the `Greenfield Peer`, a data-seed solution for those who need to run BSC nodes in fullsync mode. For more details, check out this [page](./greenfield-peer.md). ## Data Analysts and Researchers @@ -46,7 +46,7 @@ data. By leveraging Block-Archiver, they can collect reliable data for analysis, # Accessing Block Data with Block-Archiver Block-Archiver supports BSC now and its API is fully compatible with Ethereum API specifications, ensuring ease of integration for -developers. Detailed information about supported networks and endpoints can be found in [network and endpoints](../network-endpoint/endpoints.md#Block Archiver). For more details +developers. Detailed information about supported networks and endpoints can be found in [network and endpoints](../network-endpoint/endpoints.md#block-archiver). For more details about the API spec, please refer to [Block-Archiver API](https://github.com/bnb-chain/greenfield-bsc-archiver/?tab=readme-ov-file#block-archiver-api) # Try It Out diff --git a/docs/bnb-greenfield/for-developers/data-archive/greenfield-peer.md b/docs/bnb-greenfield/for-developers/data-archive/greenfield-peer.md index d912ba3892..bb5fe1ca7c 100644 --- a/docs/bnb-greenfield/for-developers/data-archive/greenfield-peer.md +++ b/docs/bnb-greenfield/for-developers/data-archive/greenfield-peer.md @@ -5,7 +5,7 @@ keywords: [ BNB Greenfield, NodeReal, Data Archive Layer, Greenfield Peer] # Greenfield Peer -With the launch of the [block-archiver](../block-archiver), BSC historical block data is now accessible on Greenfield. +With the launch of the [block-archiver](./block-archiver.md), BSC historical block data is now accessible on Greenfield. For those operating BSC nodes in fullsync mode, connecting to the Greenfield peer is a beneficial choice. The Greenfield peer fetches block data from Greenfield and supplies it to BSC nodes via the P2P network. diff --git a/docs/bnb-smart-chain/developers/paymaster/overview.md b/docs/bnb-smart-chain/developers/paymaster/overview.md new file mode 100644 index 0000000000..d4968cf4af --- /dev/null +++ b/docs/bnb-smart-chain/developers/paymaster/overview.md @@ -0,0 +1,92 @@ +--- +title: Overview - BSC Paymaster +--- + +# EOA Based Paymaster +This document introduces a paymaster solution specifically designed for Externally Owned Account (EOA) wallets, +differing from the paymaster defined in EIP-4337. With minimal modifications, wallets can integrate this solution to +support gas fee sponsorship, significantly enhancing user experience. + + +## What is EOA based Paymaster + +The paymaster in [EIP-4337](https://github.com/ethereum/ercs/blob/master/ERCS/erc-4337.md) (Account Abstraction via +Entry Point Contract Specification) is a crucial component designed to enhance the flexibility and user experience of +Ethereum transactions. It allows a third party to pay for a user's transaction fees, removing the need for users to +hold ETH to pay for gas. + +While EIP-4337 introduced the revolutionary concept of paymasters for smart contract wallets, a significant portion of +the Ethereum ecosystem still relies on EOAs. Recognizing this, this present a groundbreaking paymaster solution +specifically designed for EOA wallets. This innovation brings the benefits of transaction sponsorship and enhanced +user experience to the broader BNB Chain user base, without requiring a shift to smart contract wallets. The EOA +paymaster solution aims to democratize access to sponsored transactions, making blockchain interactions more +user-friendly and cost-effective for millions of existing EOA wallet users. + +## How does it Work + +Under [BEP322](https://github.com/bnb-chain/BEPs/blob/master/BEPs/BEP322.md)'s Proposer-Builder Separation (PBS) +architecture, a significant shift occurs in transaction processing: + +1. Validator Role: Validators no longer verify individual transaction gas prices within a block. +2. Transaction Bundling: Private transactions are grouped into bundles and submitted to builders. +3. Prioritization: Builders prioritize based on the aggregate gas price of each bundle. +4. Intra-Bundle Flexibility: Within a single bundle, gas prices can vary, allowing for zero-fee and higher-fee transactions to coexist. + +This flexibility enables innovative features such as sponsored gas fees and gasless transactions. + + +### Definitions + +**Bundle**: An ordered array of transactions that execute atomically, ensuring all transactions in the bundle are +processed together or not at all. + +**Builder**: A new stakeholder in the MEV supply chain responsible for constructing blocks. Builders package transaction bundles, +individual transactions from the public txpool, and private transaction order flow into proposed blocks. + +**Proposer**: A validator who selects the most profitable block from multiple builders' proposals for inclusion in the blockchain. + +**Paymaster**: An infrastructure component that enables transaction sponsorship, allowing self or third parties to cover gas fees. + +**Sponsor Policy**: A set of rules defined by the gas sponsor to determine which transactions qualify for sponsorship. +This may include criteria such as whitelisted transaction senders or specific transaction types. + +### Overall Workflow + +![workflow](../../img/paymaster-workflow.png) + +The gas sponsorship process involves several key components and steps: + +1. User Initiation: + - A user prepares a transaction using any compatible wallet. + - The wallet sets the gas price to zero for potentially sponsored transactions. + +2. Paymaster Submission: + - The wallet submits the zero-gas-price transaction to the Paymaster. + +3. Sponsor Policy Verification: + - The Paymaster checks the transaction against existing sponsor policies. + - Policies may include criteria such as sender/recipient addresses, token types, or transaction limits. + +4. Sponsorship Processing: + - If the transaction is eligible for sponsorship: + a. The Paymaster creates a sponsor transaction with a higher gas price. + b. The original user transaction and the sponsor transaction are combined into a bundle. + - If not eligible, the transaction is rejected or returned to the user for normal processing. + +5. Bundle Creation and Submission: + - This bundle is submitted to multiple MEV builders. + +6. Builder Selection and Block Proposal: + - MEV builders incorporate the bundle into their block proposals. + +7. Blockchain Inclusion: + - Proposers (validators) select the most profitable block from the builders' proposals. + - The selected block, containing both the user's original transaction and the sponsor's transaction, is added to the blockchain. + - This ensures atomic execution of both transactions. + +8. Post-Transaction Processing: + - The Paymaster Manager updates the sponsor's account, deducting the appropriate amount for the sponsored gas. + +This solution leverages the BEP322 Proposer-Builder Separation architecture to enable seamless gas sponsorship without +requiring significant changes to existing wallet infrastructures. It provides a flexible system that can accommodate +various sponsorship models while maintaining the security and integrity of the blockchain network. \ No newline at end of file diff --git a/docs/bnb-smart-chain/developers/paymaster/paymaster-api.md b/docs/bnb-smart-chain/developers/paymaster/paymaster-api.md new file mode 100644 index 0000000000..172b96a01a --- /dev/null +++ b/docs/bnb-smart-chain/developers/paymaster/paymaster-api.md @@ -0,0 +1,102 @@ +--- +title: Paymaster-API - BSC Paymaster +--- + +# Paymaster API Spec + +To facilitate widespread adoption and ensure interoperability across diverse wallet implementations, it is crucial to establish a standardized set of interface specifications for paymasters. This standardization will enable wallet developers to integrate gas sponsorship features efficiently and consistently, regardless of the specific paymaster service they choose to utilize. + +## API Spec + +Paymaster needs to implement a JSON-RPC API called `pm_isSponsorable`, so that it can return sponsor and policy information to wallets. Paymaster also needs to implement `eth_sendRawTransaction` JSON-RPC API. The detailed API Specs are defined as below: + +### pm\_isSponsorable + +**Request Parameters** + +* `jsonrpc`: The JSON-RPC protocol version ("2.0"). +* `id`: A unique identifier for the request (1 in this example). +* `method`: The method name to be invoked ("pm\_isSponsorable"). +* `params`: An array containing a single object with the following fields: + * `to`: The recipient address of the transaction. + * `from`: The sender address of the transaction. + * `value`: The value of the transaction in hexadecimal. + * `data`: Additional data for the transaction in hexadecimal. + * `gas`: The gas limit of the transaction in hexadecimal. + +**Example:** + +```plain +{ + "jsonrpc": "2.0", + "id": 1, + "method": "pm_isSponsorable", + "params": [ + { + "to": "0x...", // an address + "from": "0x...", // an address"value": "0xa1", + "data": "0x", + "value": "0x1b4", + "gas" : "0x101b4" + } + ] +} +``` + +**Response Fields** + +* `jsonrpc`: The JSON-RPC protocol version ("2.0"). +* `id`: The unique identifier for the request (1 in this example). +* `result`: An object containing the sponsorship policy details: + * (Required) `Sponsorable`: A boolean indicating whether the transaction is sponsorable (true or false). + * (Required) `SponsorPolicy`:. The name of the sponsor policy. + +**Example:** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "Sponsorable": true, + "SponsorPolicy": "a sample policy name" + } +} +``` + +### + +### eth\_sendrawtransaction + +The `eth_sendrawtransaction` API implemented by the Paymaster should follow this [Ethereum API Spec](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_sendrawtransaction). The client can create a new message call transaction or a contract creation for signed transactions via `eth_sendrawtransaction` API. + +**Request Parameters** + +The `params` should contain the signed transaction data. + +**Example:** + +```plain +{ + "jsonrpc": "2.0", + "id": 1, + "method": "eth_sendRawTransaction", + "params": [ + "0x02f86a6102850df8475800850df84758000a94cd9c02358c223a3e788c0b9d94b98d434c7aa0f18080c080a0bcb0e8ffa344e4b855c6e13ee9e4e5d22cff6ad8bd1145a93b93c5d332100c2ca03765236eba5fbb357e35014fd19ba4b3c6b87f3793bd14dddf7913fc8dcc88bf" + ] +} +``` + +**Response Fields** + +DATA, 32 Bytes - the transaction hash. + +**Example:** + +```json +{ + "id":1, + "jsonrpc": "2.0", + "result": "0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331" +} +``` \ No newline at end of file diff --git a/docs/bnb-smart-chain/developers/paymaster/wallet-integration.md b/docs/bnb-smart-chain/developers/paymaster/wallet-integration.md new file mode 100644 index 0000000000..1796dea226 --- /dev/null +++ b/docs/bnb-smart-chain/developers/paymaster/wallet-integration.md @@ -0,0 +1,39 @@ +--- +title: Paymaster Wallet Integration - BSC Paymaster +--- +# Wallet Integration + +This guide outlines the steps for wallet developers to integrate paymaster services, enabling gas fee sponsorship for their users. By following these standards, wallets can offer seamless, gasless transactions across multiple paymaster providers. + +## Interaction Workflow + +![wallet-paymaster](../../img/paymaster-wallet.png) + +Integration involves modifying the transaction creation and sending process to interact with paymaster services. For detailed information about the paymaster API interface, please refer to this document. + +The main steps are: + +1. **Transaction Preparation**: + * When a user initiates a transaction, first call `gm_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 "policy name" returned by the API. +3. **Transaction Signing**: + * Have the user sign the zero-gas-price transaction. +4. **Submission to Paymaster**: + * Send the signed transaction to the paymaster using `eth_sendRawTransaction`. +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 modifying gas price. +2. Provide clear user feedback about sponsorship status. +3. Implement proper error handling for cases where sponsorship fails. +4. Consider fallback mechanisms for non-sponsored transactions. \ No newline at end of file diff --git a/docs/bnb-smart-chain/img/paymaster-wallet.png b/docs/bnb-smart-chain/img/paymaster-wallet.png new file mode 100644 index 0000000000..047a2926f2 Binary files /dev/null and b/docs/bnb-smart-chain/img/paymaster-wallet.png differ diff --git a/docs/bnb-smart-chain/img/paymaster-workflow.png b/docs/bnb-smart-chain/img/paymaster-workflow.png new file mode 100644 index 0000000000..1b0550fb05 Binary files /dev/null and b/docs/bnb-smart-chain/img/paymaster-workflow.png differ diff --git a/mkdocs.yml b/mkdocs.yml index 0b792ea432..2a9c9c73c4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -123,6 +123,10 @@ nav: - Docker Image: ./bnb-smart-chain/developers/node_operators/docker.md - Upgrade Geth: ./bnb-smart-chain/developers/node_operators/upgrade_geth.md - Node Maintenance: ./bnb-smart-chain/developers/node_operators/node_maintenance.md + - EOA Paymaster: + - Overview: ./bnb-smart-chain/developers/paymaster/overview.md + - Paymaster API Spec: ./bnb-smart-chain/developers/paymaster/paymaster-api.md + - Wallet Integration: ./bnb-smart-chain/developers/paymaster/wallet-integration.md - Staking: - Overview: ./bnb-smart-chain/staking/overview.md - User Guide: ./bnb-smart-chain/staking/user-guide.md