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 be public or private, by defining the type of them. If a policy is private, it can only accessed by its owner. If a policy is public, it can be accessed by anyone that its whitelist allows.

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 public policy must have at least one whitelist, while a valid private policy can have no whitelist configured.

A size limit of 1000 entries is enforced for each type of whitelist (FromAccountWhitelist, ToAccountWhitelist, BEP20ReceiverWhiteList, and ContractMethodSigWhitelist). When adding new entries to any whitelist, the system will verify that the total number of entries does not exceed this limit. If you exceeded this type of whitelist limit, consider using private policy instead. This restriction helps maintain system performance and prevents potential abuse.

• 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 and transaction count 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 maximum gas fees and transaction count 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 Attributes

{
  "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"]
}

Public Policy and Private Policy

There are two kinds of policies that sponsors can create, public policy and private policy.

Public Policy

Public policy can sponsor all qualified users' transactions. If a policy owner wants to sponsor a group of users in case of events or other scenarios, public policy is the one to choose.

The sponsor who creates public policy must set up one of from or to whitelist, so that it will restrict the users that can be sponsored by the policy, to guarantee the safety of the fund inside the policy. Transactions whose from address, to address, and data matches a valid policy(non-expired, has remaining gas, etc.) and its whitelist requirements will be sponsored by that policy.

When creating a policy, it is suggested that the public policy's owner also fill in the sponsor name, sponsor icon, and sponsor website fields so that users know whose policy sponsors them.

Private Policy

Private policy can only sponsor its owner's transactions. If a policy owner only wants himself to use the policy and no one else, he shall create a private policy.

The private policy has a looser whitelist requirement. Since it is only used by its owner, it can have no whitelist configured. When using the private policy, the user will need to fill in one extra header X-MegaFuel-Policy-Uuid, and use the open-platform endpoint for identity verification. The details are on the Private Policy page.

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.

3. Type Configuration

• If an owner only wants to access the policy himself, set the policy type as private policy. Otherwise, set the type as public policy.