Skip to main content

Fuel Tanks

Please note: This is an introductory reference

For the most up-to-date information, refer to the API Reference.
🚧 The information provided in this section cannot be programmatically updated and may be subject to inconsistencies over time.

Fuel Tanks Endpoints
  • Testnet: http://platform.canary.enjin.io/graphql/fuel-tanks
  • Mainnet: http://platform.enjin.io/graphql/fuel-tanks

This is a detailed reference guide that explains the most commonly used operations.

CreateFuelTank​

The CreateFuelTank mutation is used to create a new fuel tank within a system, allowing you to establish specific attributes and rules that govern how accounts can be added and how transactions are dispatched from it. This mutation is a fundamental step in setting up the infrastructure for managing accounts and transactions within a network, providing a customizable framework to tailor the tank's behavior to your specific requirements.

mutation CreateFuelTank {
  CreateFuelTank(
    name: "My Fuel Tank"
    coveragePolicy: FEES_AND_DEPOSIT
    reservesAccountCreationDeposit: false
    requireAccount: true
    accountRules: {requireToken: {collectionId: "7406", tokenId: {integer: 5839}}, whitelistedCallers: ["0x66f522f1e17f25b3942916dcc60d92f0f8bc27d40083fadf5d65e9dd5f646009"]}
    dispatchRules: [{requireToken: {collectionId: "7406", tokenId: {integer: 5839}}, whitelistedCallers: ["0x66f522f1e17f25b3942916dcc60d92f0f8bc27d40083fadf5d65e9dd5f646009"], whitelistedCollections: null, maxFuelBurnPerTransaction: 0, userFuelBudget: {amount: 1, resetPeriod: 1}, tankFuelBudget: {amount: 1, resetPeriod: 1}}]
  ) {
    id
    transactionId
    transactionHash
    state
    encodedData
    method
    wallet {
      account {
        publicKey
        address
      }
    }
    idempotencyKey
  }
}

DestroyFuelTank​

The DestroyFuelTank mutation is used to permanently remove an existing fuel tank from the system. This operation is essential for efficient resource management, allowing you to clean up unused or unnecessary fuel tanks within your network infrastructure.

mutation DestroyFuelTank {
  DestroyFuelTank(tankId: "cxMyyy9aiu8Wv8PDtnjkuSKzJ7n854hQNcNETZiHVS3s3xPhr") {
    id
    transactionId
    transactionHash
    state
    encodedData
    method
    wallet {
      account {
        publicKey
        address
      }
    }
    idempotencyKey
  }
}

AddAccount​

The AddAccount mutation is used to add a new account to an existing fuel tank. This operation is crucial when you need to grant access to specific users, allowing them to utilize the resources and perform authorized actions within the fuel tank.

mutation AddAccount {
  AddAccount(
    tankId: "cxNkbpQpiiza3JCH9fxmt6eJ8vDSFqzqVfz2a543QbPG4sN9K"
    userId: "cxMsNPRk7Ek5V76NC4o2HTBrnxcUnxLA9btuKPcuPkmYi84Ts"
  ) {
    id
    transactionId
    transactionHash
    state
    encodedData
    method
    wallet {
      account {
        publicKey
        address
      }
    }
    idempotencyKey
  }
}

BatchAddAccount​

The BatchAddAccount mutation is designed for efficiently adding multiple new user accounts to a specified fuel tank in a single batch operation. This feature is particularly useful when you need to add several accounts at once, reducing the number of individual requests and optimizing resource usage.

mutation BatchAddAccount {
  BatchAddAccount(tankId: "cxNkbpQpiiza3JCH9fxmt6eJ8vDSFqzqVfz2a543QbPG4sN9K", userIds: ["cxMsNPRk7Ek5V76NC4o2HTBrnxcUnxLA9btuKPcuPkmYi84Ts","cxLc8HSeuiLiYmEG7XB8wQrbkRPNCaDi5dVpqPkyhWdEp6i63"]) {
    id
    transactionId
    transactionHash
    state
    encodedData
    method
    wallet {
      account {
        publicKey
        address
      }
    }
    idempotencyKey
  }
}

BatchRemoveAccount​

The BatchRemoveAccount mutation is designed for efficiently removing multiple user accounts from a specified fuel tank in a single batch operation. This feature is particularly useful when you need to remove several accounts at once, reducing the number of individual removal requests and optimizing resource usage.

mutation BatchRemoveAccount {
  BatchRemoveAccount(tankId: "cxMyyy9aiu8Wv8PDtnjkuSKzJ7n854hQNcNETZiHVS3s3xPhr", userIds: ["cxLkamf2QxHK9bcqhh56QAFc8TTmvWG33sUbkNakJV4yzdDcz"]) {
    id
    transactionId
    transactionHash
    state
    encodedData
    method
    wallet {
      account {
        publicKey
        address
      }
    }
    idempotencyKey
  }
}

Dispatch​

The Dispatch mutation is a powerful operation that allows you to trigger specific actions within a system using a designated fuel tank (tankId) while adhering to predefined rules specified by a rule set (ruleSetId). This mutation is especially useful when you want the fuel tank to handle transaction fees and potentially storage deposits for the dispatched call.

mutation Dispatch {
  Dispatch(
    tankId: "cxMyyy9aiu8Wv8PDtnjkuSKzJ7n854hQNcNETZiHVS3s3xPhr"
    ruleSetId: 0
    dispatch: {
      call:FUEL_TANKS
      query:"mutation { AddAccount(tankId: \"cxMyyy9aiu8Wv8PDtnjkuSKzJ7n854hQNcNETZiHVS3s3xPhr\", userId: \"cxMsNPRk7Ek5V76NC4o2HTBrnxcUnxLA9btuKPcuPkmYi84Ts\") { id encodedData } }"
      variables:null
    }
    paysRemainingFee: false
  ) {
    id
    transactionId
    transactionHash
    state
    encodedData
    method
    wallet {
      account {
        publicKey
        address
      }
    }
    idempotencyKey
  }
}

DispatchAndTouch​

The DispatchAndTouch mutation combines the functionalities of the Dispatch mutation with the ability to create an account for the calling entity (origin) if it doesn't already exist. This mutation is especially valuable in scenarios where the caller's account may not have been set up in advance, streamlining the process of both executing an operation and ensuring account existence.

mutation DispatchAndTouch {
  DispatchAndTouch(
    tankId: "cxMyyy9aiu8Wv8PDtnjkuSKzJ7n854hQNcNETZiHVS3s3xPhr"
    ruleSetId: 0
    dispatch: {
      call:FUEL_TANKS
      query:"mutation { AddAccount(tankId: \"cxMyyy9aiu8Wv8PDtnjkuSKzJ7n854hQNcNETZiHVS3s3xPhr\", userId: \"cxMsNPRk7Ek5V76NC4o2HTBrnxcUnxLA9btuKPcuPkmYi84Ts\") { id encodedData } }"
      variables:null
    }
    paysRemainingFee: false
  ) {
    id
    transactionId
    transactionHash
    state
    encodedData
    method
    wallet {
      account {
        publicKey
        address
      }
    }
    idempotencyKey
  }
}

SetConsumption​

The SetConsumption mutation enables you to manually set the fuel consumption for a specific fuel tank. It allows you to override the current fuel consumption data with the values provided in the mutation arguments. This can be useful for making adjustments, corrections, or administrative changes to fuel consumption records.

mutation SetConsumption {
  SetConsumption(
    tankId: "cxMyyy9aiu8Wv8PDtnjkuSKzJ7n854hQNcNETZiHVS3s3xPhr"
    ruleSetId: 0
    userId: "cxLkamf2QxHK9bcqhh56QAFc8TTmvWG33sUbkNakJV4yzdDcz"
    totalConsumed: 10
    lastResetBlock: 100
  ) {
    id
    transactionId
    transactionHash
    state
    encodedData
    method
    wallet {
      account {
        publicKey
        address
      }
    }
    idempotencyKey
  }
}

InsertRuleSet​

The InsertRuleSet mutation is used to add a new rule set to a fuel tank. It allows you to define specific rules and requirements for the fuel tank's operation.

mutation InsertRuleSet {
  InsertRuleSet(
    tankId: "cxMyyy9aiu8Wv8PDtnjkuSKzJ7n854hQNcNETZiHVS3s3xPhr"
    ruleSetId: 1
    dispatchRules: { requireToken: {collectionId: "7153", tokenId: {integer: 68}} }
  ) {
    id
    transactionId
    transactionHash
    state
    encodedData
    method
    wallet {
      account {
        publicKey
        address
      }
    }
    idempotencyKey
  }
}

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.

Whitelisted Callers​

Whitelisted callers are accounts that are explicitly granted permission to make calls to a fuel tank. Any calls made by accounts not on the whitelist will be rejected and fail.

Whitelisted Collections​

Whitelisted collections refer to a list of specific collections allowed to be called by dispatch on a fuel tank. If a dispatch call is made to any collection, not on the whitelist, it will be rejected and fail. This ensures that calls are only made to the specific collections authorized to be accessed.

Max Fuel Burn Per Transaction​

It is a setting that limits the amount of fuel that can be consumed in a single transaction. It is a safety measure that helps prevent misuse and overuse of the fuel tank's resources by ensuring that a single transaction doesn't consume too much fuel, which is important to ensure a sustainable network.

User Fuel Budget​

A user fuel budget is the total amount of fuel allocated to a specific user across all rule sets of a fuel tank. It sets a limit on the amount of fuel that can be consumed by a user's transactions. Once the user's fuel budget is exhausted, their transactions will fail until more fuel is added to their budget or their overall consumption is lowered , which is meant to avoid the overuse of resources and ensure a sustainable network.**

Tank Fuel Budget​

A tank fuel budget is the total amount of fuel allocated to a specific fuel tank across all its rule sets. It sets a limit on the amount of fuel that can be consumed by all transactions made through that tank. Once the tank's fuel budget is exhausted, all transactions will fail until more fuel is added to the tank's budget or overall consumption is lowered.

Require Token​

The "Require token" setting indicates that a specific token must be held by the caller for their call to be accepted by the fuel tank. If the caller does not possess the required token, their call will be rejected and fail. This feature is intended to ensure that only users who hold the specified token can access the fuel tank's functions and resources.

Permitted Calls​

Permitted calls refer to a list of specific function calls that are allowed to be made using this rule set. Any calls made to other functions will be rejected and fail. This ensures that only authorized calls can be made by the users, and also, by setting a boundary to what calls are allowed and what calls are not, it helps to protect the network from unwanted transactions that could impact negatively on the network.

Permitted Extrinsics​

Permitted extrinsics refer to a list of specific extrinsics that are allowed to be made using this rule set. Any extrinsics that are not on the list will be rejected and fail. This feature is used to restrict access to specific functionality and resources on the network and ensure that only authorized calls can be made by users. When setting this rule, it's important to note that the parameters passed to the extrinsic do not affect the outcome, only the function name is considered.**

Freezing​

"Freezing" is a state where a fuel tank or a rule set is temporarily prevented from accepting calls or making changes. This means that while a fuel tank or rule set is frozen, no dispatches are allowed to occur on it. This is implemented as a safety measure to prevent accidental or malicious changes and to ensure that the fuel tank or rule set remains in a stable state until the freeze is lifted.

Descriptor​

A descriptor is a list of all the data needed to create a fuel tank. It includes details such as the fuel tank's name, account management rules, rule sets and other configuration information related to the fuel tank. The descriptor acts as a blueprint that defines how the fuel tank is set up and how it will function. It contains all the information needed to create and configure the fuel tank, and can be used to modify the fuel tank's settings.

MutateFuelTank​

The MutateFuelTank mutation is used to apply a specific mutation to a fuel tank. This mutation allows you to modify the Fuel Tank configuration.

mutation MutateFuelTank {
  MutateFuelTank(tankId: "cxLt3kZZHgz4pqGgaQWjxCRXGd81ey7YRwycGcRnZrNtfpbAs",
    mutation: {
      coveragePolicy: FEES_AND_DEPOSIT,
      reservesAccountCreationDeposit: true
      accountRules: {
        whitelistedCallers: [
          "cxKy7aqhQTtoJYUjpebxFK2ooKhcvQ2FQj3FePrXhDhd9nLfu",
          "cxKRcxyqEuj8qwS4qAmxZMLKNoMJPMhQBLhoQdKekubbo3BtP"
      	]
      }
    }
  ){
    id
    transactionId
    transactionHash
    state
    encodedData
    method
    wallet {
      account {
        publicKey
        address
      }
    }
    idempotencyKey
  }
}

RemoveAccount​

The RemoveAccount mutation is used to remove a specified user account from a fuel tank. This mutation is particularly useful for managing the accounts associated with a fuel tank.

mutation RemoveAccount {
  RemoveAccount(tankId: "cxMyyy9aiu8Wv8PDtnjkuSKzJ7n854hQNcNETZiHVS3s3xPhr", userId: "cxLkamf2QxHK9bcqhh56QAFc8TTmvWG33sUbkNakJV4yzdDcz") {
    id
    transactionId
    transactionHash
    state
    encodedData
    method
    wallet {
      account {
        publicKey
        address
      }
    }
    idempotencyKey
  }
}

RemoveAccountRuleData​

The RemoveAccountRuleData mutation is used to delete specific rule data associated with an account on a fuel tank. This allows you to remove certain restrictions or requirements that were previously set for an account's interactions with the fuel tank.

mutation RemoveAccountRuleData {
  RemoveAccountRuleData(
    tankId: "cxMyyy9aiu8Wv8PDtnjkuSKzJ7n854hQNcNETZiHVS3s3xPhr"
    ruleSetId: 0
    userId: "cxLkamf2QxHK9bcqhh56QAFc8TTmvWG33sUbkNakJV4yzdDcz"
    rule: REQUIRE_TOKEN
  ) {
    id
    transactionId
    transactionHash
    state
    encodedData
    method
    wallet {
      account {
        publicKey
        address
      }
    }
    idempotencyKey
  }
}

RemoveRuleSet​

The RemoveRuleSet mutation is utilized to completely remove an existing set of rules from a specified fuel tank. Rule sets represent collections of conditions or constraints that govern the usage and access to the fuel tank. Removing a rule set becomes necessary when you need to modify operational policies, or a rule set is no longer applicable to the fuel tank's operations.

mutation RemoveRuleSet {
  RemoveRuleSet(tankId: "cxMyyy9aiu8Wv8PDtnjkuSKzJ7n854hQNcNETZiHVS3s3xPhr", ruleSetId: 0) {
    id
    transactionId
    transactionHash
    state
    encodedData
    method
    wallet {
      account {
        publicKey
        address
      }
    }
    idempotencyKey
  }
}

ScheduleMutateFreezeState​

The ScheduleMutateFreezeState mutation enables you to schedule a change in the is_frozen state of either a fuel tank or a rule set. This state determines whether the tank or rule set can be frozen (immobilized), preventing any operations that could alter its configuration or state.

mutation ScheduleMutateFreezeState {
  ScheduleMutateFreezeState(
    tankId: "cxMyyy9aiu8Wv8PDtnjkuSKzJ7n854hQNcNETZiHVS3s3xPhr"
    ruleSetId: 0
    isFrozen: true
  ) {
    id
    transactionId
    transactionHash
    state
    encodedData
    method
    wallet {
      account {
        publicKey
        address
      }
    }
    idempotencyKey
  }
}