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:

1. Global Gas Fee Cap. The maximum amount of gas fees that the entire policy can cover, establishing an overall budget for sponsored transactions.
2. 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:

1. 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.
2. Updates: The sponsor has the exclusive right to modify the policy's parameters.
3. 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.
4. Reactivation: A deactivated policy can be reactivated by its owner, restoring its ability to be used for transaction evaluation.

Policy Breakdown

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:

1. 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.

2. Manage Whitelist - Utilize the pm_addToWhitelist and pm_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

1. policyUuid - The uuid of policy for which the whitelist is modified.
2. whitelistType - One of the following values:
   1. FromAccountWhitelist - This whitelist restricts the senders of sponsored transactions.
   2. ToAccountWhitelist - This whitelist restricts the contract addresses that sponsored transactions can interact with.
   3. BEP20ReceiverWhiteList - This whitelist restricts the token receiver addresses for sponsored transactions when the contract call is BEP20 transfer method.
   4. ContractMethodSigWhitelist - This whitelist restricts the contract methods that sponsored transactions can call.
3. 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.

Activating and deactivating policies

The policy owner can activate or deactivate their own policy. They can:

1. deactivate a policy using pm_deactivatePolicy api.
2. activate a policy using pm_activatePolicy api.

Best Practices

Guidelines for Effective Policy Definition

1. 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.

2. Whitelist Configuration

• Configure 'to' or 'from' whitelists immediately upon policy creation.
• Note: A policy without at least one whitelist will not take effect.