Policy Management
Introduction
Policies serve as the determinants for transaction sponsorship by the MegaFuel. These policies, created and maintained exclusively by the sponsor. Upon receipt of a transaction, the system evaluates it against all existing policies. If the transaction meets the requirements of any policy, the MegaFuel will proceed with sponsorship.
Note: At present, during the beta phase, policies can only be created by the system after a sponsor initiates an application.
Policy Model
Key Attributes
- Expiry and Duration
Policies are governed by temporal and activation parameters to control their sponsorship lifecycle. Each policy has defined start and end times, determining its period of validity. Policies can be activated or deactivated anytime.
- Access Control
Policies can define transaction whitelist for both from
and to
addresses. The MegaFuel will only sponsor a transaction based on a specific policy if the sender's address or the to address is included in the respective whitelist. A valid policy must have at least one whitelist.
- Contract Call Traits
The calldata
of a transaction consists of two parts: the method signature and its associated parameters. Currently, policies have the capability to define a whitelist of allowed method signatures. This feature enables fine-grained control over which contract functions can be invoked under a specific policy. In the near future, we plan to implement enhanced validation for parameters.
- Policy Spending Rules
The spending rules define the gas cost limitations of policy, including:
- Global Gas Fee Cap. The maximum amount of gas fees that the entire policy can cover, establishing an overall budget for sponsored transactions.
- Per-Account Limits. The the maximum gas fees that can be sponsored for each individual sender account.
Lifecycle
A policy progresses through several stages throughout its existence:
- Creation and Activation: Upon creation, a policy is automatically activated and becomes immediately available for transaction validation. This ensures that newly created policies can be utilized without delay.
- Updates: The sponsor has the exclusive right to modify the policy's parameters.
- Deactivation: At any point, the sponsor can choose to deactivate the policy. In this state, the policy is suspended and cannot be used for transaction pairing.
- Reactivation: A deactivated policy can be reactivated by its owner, restoring its ability to be used for transaction evaluation.
Policy Breakdown
Fileds | Type | Description |
---|---|---|
uuid | string | Universally Unique Identifier for the policy |
name | string | Human-readable name of the policy |
network | uint32 | Network ID where this policy is applicable (e.g., 97 for BSC testnet) |
type | uint8 | Type of policy (0 represent a standard policy) |
owner | uuid(string) | UUID of the policy owner/sponsor |
maxGasCostPerAddr | string | the upper limit of gas costs that the policy can sponsor for a single address throughout the policy's lifetime |
maxGasCostPerAddrPerDay | string | the upper limit of gas costs that the policy can sponsor for a single address within a 24-hour period. |
maxGasCost | string | the absolute upper limit for the total gas costs that the policy can sponsor across all addresses throughout its lifetime |
minSupportedAmount | string | the lower limit of value in the tx when transferring a BEP20 token |
start | int64 | time the policy to be considered becoming activated |
end | int64 | time the policy to be considered becoming deactivated |
activated | boolean | if a policy is ready to use or not |
fromAccountWhitelist | []string | policy allow the tx with whitelisted from account |
toAccountWhitelist | []string | policy allow the tx with whitelisted from account |
ContractMethodSigWhitelist | []string | policy allow the tx with whitelisted contract method signature in data. An optional field |
BEP20ReceiverWhiteList | []string | policy allow the tx with whitelisted bep 20 receiver in data, only if ContractMethodSig equal to 0xa9059cbb. An optional field |
Example Policy
{
"uuid":"9d8e468e-3288-401a-bdc2-e45d6f09461f",
"name":"new_policy_1",
"type":0,
"network":97,
"owner":"0660af77-8c74-4d9a-9106-afe2cbc18375",
"start":1721112188,
"end":1831112188,
"updateTimestamp":1722832684,
"maxGasCostPerAddr":"12000000000000",
"maxGasCostPerAddrPerDay":"1200000000000",
"maxGasCost":"12000000000000000",
"minSupportedAmount": "0",
"activated":true,
"fromAccountWhitelist":["0xf39Fd6e51aad88F6F4ce6aB8827ab7cffFb92255"],
"toAccountWhitelist":["0xdAC17F958D2ee523a2206206994597C13D931ec7", "0x0000000000085d4780B73129b644AE5ecd22b376"],
"contractMethodSigWhitelist":["0xae5ecdaf","0x2ee597c7"],
"BEP20ReceiverWhiteList":["0x4ECac3cf248C96D9AAaCc3d3ddC54504d50eb604"]
}
Policy Management
Creating a new policy
Only approved sponsors are authorized to create policies. At present, all transaction fees associated with sponsored transactions are covered by BNB Chain funding. Therefore direct policy creation by sponsors is not available. Policies are created and primarily managed by system after being approved.
Please refer to this document for guidelines on how to apply to Become a Sponsor and submit a google form to create a sponsorship policy.
Updating existing policies
Policy modifications are restricted to the respective policy owners. Policy owners have the following capabilities:
-
Update Policy - Utilize the
pm_updatePolicy
API to modify existing policy parameters, including the spending rules, expiry and duration. Similar to "Creating a new Policy", at present, direct policy updating by sponsors is not available. -
Manage Whitelist - Utilize the
pm_addToWhitelist
andpm_rmFromWhitelist
API to update the access control, contract call traits.
Update Policy Whitelist Based on Values and WhitelistType
{
"jsonrpc": "2.0",
"id": 1,
"method": "pm_addToWhitelist",
"params": [
{
"policyUuid": "62a1e2e5-4505-48fd-9223-fa9fd5c9dce0",
"whitelistType": "FromAccountWhitelist",
"values": [
"0xF9A8db17431DD8563747D6FC770297E438Aa12eB"
]
}
]
}
Parameters
policyUuid
- The uuid of policy for which the whitelist is modified.whitelistType
- One of the following values:FromAccountWhitelist
- This whitelist restricts the senders of sponsored transactions.ToAccountWhitelist
- This whitelist restricts the contract addresses that sponsored transactions can interact with.BEP20ReceiverWhiteList
- This whitelist restricts the token receiver addresses for sponsored transactions when the contract call is BEP20 transfer method.ContractMethodSigWhitelist
- This whitelist restricts the contract methods that sponsored transactions can call.
values
- Hex values that will be added into above whitelistType.
Guidelines for Values Definition
The policy’s whitelist should be updated based on the values
provided and the specified WhitelistType.
- FromAccountWhitelist/ToAccountWhitelist/BEP20ReceiverWhiteList:
- For all other types, the input required is the user’s account address. The account address on BSC is typically a 20-byte hexadecimal number uniquely identifying an account on the network.
- ContractMethodSigWhitelist:
- If the whitelist type is ContractMethodSigWhitelist, then the
values
should contain a contract method signature. For example,0xfce353f6
. - The contract method signature is derived using the ABI encoding method defined in the Solidity documentation on Function Selector and Argument Encoding. The ABI (Application Binary Interface) specifies how data is formatted in the BSC ecosystem, facilitating the interaction between binary program interfaces. Function selectors in Solidity are computed as the first four bytes of the Keccak-256 hash of the function’s signature, which ensures that calls can be correctly routed to their respective functions within the contract.
- Example: For the method transfer(address,uint256), the signature is calculated using the formula:
bytes4(keccak256(bytes('transfer(address,uint256)'))) = 0xa9059cbb
This calculation ensures that calls can be correctly routed to their respective functions within the contract.
- If the whitelist type is ContractMethodSigWhitelist, then the
Activating and deactivating policies
The policy owner can activate or deactivate their own policy. They can:
- deactivate a policy using
pm_deactivatePolicy
api. - activate a policy using
pm_activatePolicy
api.
Best Practices
Guidelines for Effective Policy Definition
- Gas Cost Limits
- Be explicit about gas cost limitations. It is default to infinity if not specified. Ensure this aligns with your intended policy behavior.
- Whitelist Configuration
- Configure 'to' or 'from' whitelists immediately upon policy creation.
- Note: A policy without at least one whitelist will not take effect.
Updated 23 days ago