How to Use Fuel Tanks

The purpose of this guide is to provide an overview of the concepts that revolve around fuel tanks on Efinity, as well as an extensive guide on how to set fuel tanks for your integration using Polkadot.js.

What is a Fuel Tank?

A fuel tank is a feature that allows users to interact with Efinity, without incurring transaction fees. It is essentially a pool of tokens used by multiple accounts (wallets) to make calls on Efinity. It can have various settings and rules for paying transaction fees and providing storage deposits. Fuel tanks can be modified using the Polkadot.JS interface or by setting specific parameters using the fuel tank pallet.

Similar to a car with gas, all your friends can ride in the car for free and have a happy road trip with you!

Why should developers use a Fuel Tank?

A fuel tank's primary purpose is to let users interact and use Efinity without paying transaction fees.

A fuel tank can be created by anyone using the create_fuel_tank extrinsic function. Once the fuel tank is created, it’s possible to add funds to it and subsidize transactions permitted by the fuel tank.

Transaction fees are required to maintain the security of a parachain. However, this frequently becomes a barrier to adoption because users cannot use a parachain without first purchasing some tokens to cover transaction fees, and most users who are new to blockchain would find it extremely difficult to buy tokens and transfer them to a wallet to engage with NFT projects or play games.

A fuel tank will subsidize/completely cover transaction costs for the user subject to rules set by the fuel tank creator.

Important Bookmarks 🔖

1. Efinity Explorer
2. Efinity Subscan Explorer

Terminology

Rules

When a call is made to a fuel tank, it must be made in accordance with a set of rules. These rules, known as rule sets, can include multiple individual rules that determine the validity of the call. A fuel tank can have multiple rule sets, each of which controls access and permissions to the fuel tank's functionality and resources.

A. Creating a Fuel Tank

Preparations

• Make sure you have your Polkadot.js extension installed and you have a valid EFI balance on it to pay for the network costs and set up the fuel tank.
• Visit this page and connect to your Polkadot.js wallet.
• Hover over the "Network" drop-down menu in the top bar and click on "Fuel Tanks". You will now see a list of all existing fuel tanks as well as a "Create Fuel Tank" button in the top-right corner:

1. Create a Fuel Tank using the Efinity Explorer

• Name: Name for the fuel tank
• User Account Management: (Optional) Permits setting the permission level to add new accounts to the fuel tank.
• Provides Deposit: This allows specifying if the fuel tank is providing a storage deposit for operations that require it.
• Account Rules: (Optional) Allows specifying rules that are evaluated before an account is added to the fuel tank. Please refer to the terminology section for a high-level description or the notes in the fuel tank creation page.
• Dispatch Rules: (Optional) Allows specifying rules that are evaluated before an operation is executed via the fuel tank. Please refer to the terminology section above for a high-level description or refer to the notes in the fuel tank creation page.

Example Basic Fuel Tank Creation

In the screenshot below, we can see how to create a basic fuel tank with entry-level rules, where only the account Tassio (our test account) can join the fuel tank and dispatch an operation via the fuel tank.

B. Modifying an already existing Fuel Tank

To mutate or modify a fuel tank, the caller must be the owner of the fuel tank; otherwise, the platform will return an error related to permissions. It’s also important to freeze the tank before mutating it, so that it cannot perform any transactions while being mutated.

To mutate a fuel tank using the Efinity Explorer, head to the Network tab and click on “Fuel Tanks”.

From there, you will see your fuel tank, and you can also click on the drop-down arrow to show all available options. Please note that you will be able to interact with fuel tanks created by your account.

Mutating the already existing fuel tank involves 3 simple steps:

C. Adding a new account to an already existing Fuel Tank

This command allows you to add a new fuel tank user account. This allows the use of the fuel tank and storing consumption and ruleset data for the user and the fuel tank. An account can only be created if the rules are validated.

It’s important to note that a storage deposit is required for this, which, depending on the settings, may be paid by the user or the fuel tank itself.

It’s also important to note that this could fail with NoPermission if the caller is not the owner and the user management settings don't allow users to create accounts on their own. Creation of an already existing account within a tank will result in AccountAlreadyExists error. A rule-specific error will be returned if some account rules cannot validate the caller. In success, it emits an  AccountAdded event.

In this screenshot, we can see that the Tassio Efinity Wallet is adding Tassio Account to the Fuel Tank.

D. Removing an account from an already existing Fuel Tank

This command allows you to remove a user account from a fuel tank and return the storage deposit to the account which paid for it. To remove an account from the fuel tank, make sure that the fuel tank is frozen, as the operation cannot be executed otherwise. Removing all rule data from that specific account is important to prevent any errors.

In this screenshot, we can see that the Fuel Tank owner ALICE is removing BOB from the fuel tank.

E. Removing rule data from an account

To enforce the fuel tank’s budget and max spending limits, the fuel tank stores data for every account. This command allows the removal of user account rule data if it exists. This also requires the fuel tank or the rule set to be frozen to prevent errors. This call is only able to be performed by the Fuel Tank owner.

F. Dispatching a transaction with your Fuel Tank

Dispatch a call through the fuel tank, where the tank would pay for transaction fees and, if configured, provide a storage deposit. All calls are subject to rule set evaluation and would result in rule-specific errors in case of failure. If the inner call fails, the DispatchFailed event will be emitted with a wrapped dispatch error inside. If successful, case emits Dispatched event.

Inside the dialog box that opens, select

• The extrinsic you want to call via the fuel tank;
• The rule set id you wish to apply to the transaction;
• The extrinsic to execute;
• If willing to pay for transaction fees that exceed the fuel tank budget threshold.

G. Creating your own collection Fuel Tank!

Last but not least, we will go through the process of creating a fuel tank that pays for transactions for your own game/project!

As a game developer building on Efinity, you would have some tokens created by your collection.  Having a fuel tank set-up for your collection would allow users to acquire your in-game items by subsidizing their transactions.

As a good set of rules, we have the following suggested guidelines —

1. You only want to subsidize transactions that are connected to your game.
2. You should set an upper limit on the amount to subsidize for a single transaction to prevent abuse.
3. You want to encourage more players to try out the fuel tank, so you also need a rolling budget to ensure a few heavy hitters do not initially deplete your fuel tank.

1. Assuming that you have many in-game assets (tokens) all grouped under a single collection ID, we will create a fuel tank that allows transactions that deal with this single collection. Any other transactions will be rejected. This takes care of rule number one.
2. We will use the MaxFuelBurnPerTransaction rule to set the max fuel burn in a single transaction to 1 EFI.
3. We will set the TankFuelBudget rule to 2 EFI and allow it to reset every five blocks so that it is possible only to deplete 2 EFI at every five block interval.

The created fuel tank transaction should look like this —

Now that this fuel tank has enough funds, we can run some tests to ensure all the rules are working as expected!

Using a new account, we can try to dispatch a balance transfer via the fuel tank.

In this example, we use the Ferdie account to transfer 1 EFI to Alice. Our fuel tank should reject this since we have set up the rules only to allow transactions that deal with our Collection ID.

Let's try to do another transaction. Here we create a dispatch call for a transaction that sets the attributes for a token within the permitted collection ID. This should result in a successful transaction.

The screenshot below, shows us what a successful dispatch looks like.

Fuel tanks will be a game changer for adoption with unmatched flexibility to set rules at user level. Efinity brings true disruption to those building on blockchain.

To Efinity and beyond!