Gas Bank Service

Key Features

• Sponsor transactions for your users, removing the gas barrier to entry
• Bulk gas management for high-volume applications
• Configurable gas limits and spending policies
• Detailed gas usage analytics and reporting
• Pay-as-you-go and subscription pricing models
• Seamless integration with other Service Layer components
• Role-based access controls for team management

How Gas Bank Works

The Gas Bank Service works by maintaining a pool of GAS that can be used to sponsor transactions on behalf of your application and its users.

1. Gas Deposit: You deposit GAS to your Gas Bank account, which becomes available for your application to use
2. Policy Configuration: You define spending policies that determine how and when your gas can be used
3. Transaction Sponsorship: Your application requests gas for specific operations
4. Automatic Payment: The Gas Bank handles the transaction fees, deducting from your balance
5. Usage Tracking: All gas usage is tracked for transparency and accounting

Setting Up Gas Bank

Getting started with the Gas Bank Service involves a few simple steps:

1. Create a Gas Bank Account

Register for a Gas Bank account through the Service Layer dashboard or API:

POST /api/v1/gas-bank/accounts
{
  "name": "My Application Gas Bank",
  "description": "Gas bank for our DeFi application",
  "contactEmail": "team@myapp.com"
}

2. Deposit GAS

Fund your Gas Bank account by transferring GAS to your deposit address:

// Gas bank deposit address (example)
NWx5ZT9RQcM5NMbKFECMv2C38XnFNK6J6H

// Minimum deposit: 10 GAS
// Confirmation time: ~15 seconds (1 block)

3. Configure Gas Policies

Define spending policies to control how your gas can be used:

POST /api/v1/gas-bank/policies
{
  "name": "Standard Operations Policy",
  "maxGasPerTransaction": 20,
  "maxDailyGas": 500,
  "authorizedOperations": [
    "token_transfer",
    "contract_deploy",
    "contract_update"
  ],
  "allowedContractScriptHashes": [
    "0x7a16a1f5c40e69790333f3bfe7e4325a08cc2f79"
  ],
  "allowedCallerAddresses": [
    "Nb94dB266iD7JtXs3PmpQi6q7jKR4iQGpC"
  ],
  "notificationWebhook": "https://myapp.com/webhooks/gasbank"
}

Gas Bank APIs

The Gas Bank Service provides comprehensive APIs for integrating with your applications:

Request Transaction Sponsorship

POST /api/v1/gas-bank/transactions
{
  "operation": "contract_invoke",
  "scriptHash": "0x7a16a1f5c40e69790333f3bfe7e4325a08cc2f79",
  "method": "transfer",
  "args": [
    {
      "type": "Hash160",
      "value": "0x1aada0032aba1ef6d1f07bbd8bec1d85f5380fb3"
    },
    {
      "type": "Hash160",
      "value": "0x6f41f04d29e11b63e71a9d1cb17da00f33d7ca7f"
    },
    {
      "type": "Integer",
      "value": "100000000"
    }
  ],
  "signers": [
    {
      "account": "0x1aada0032aba1ef6d1f07bbd8bec1d85f5380fb3",
      "scopes": "CalledByEntry"
    }
  ],
  "broadcastNow": true
}

Check Gas Balance

GET /api/v1/gas-bank/balance

Response:
{
  "balance": "258.45931642",
  "pendingDeposits": "0",
  "reservedForPendingTransactions": "1.25000000",
  "available": "257.20931642",
  "totalSpent": "42.54068358",
  "lastUpdated": "2023-03-22T14:15:26Z"
}

Get Transaction History

GET /api/v1/gas-bank/transactions?limit=10&offset=0

Response:
{
  "transactions": [
    {
      "id": "tx_01GZQT3R8YJDZB8F3E3VPXQ9F4",
      "txid": "0x9c57c0a94e87c690ebd4d4e12e1f731c181d889b7bc5f0e7ec8f13383a699073",
      "operation": "contract_invoke",
      "scriptHash": "0x7a16a1f5c40e69790333f3bfe7e4325a08cc2f79",
      "method": "transfer",
      "gasConsumed": "0.83420000",
      "status": "confirmed",
      "timestamp": "2023-03-22T14:10:15Z"
    },
    // More transactions...
  ],
  "total": 42,
  "limit": 10,
  "offset": 0
}

Using Gas Bank with Functions

JavaScript functions can use the Gas Bank to execute blockchain transactions:

async function main(args) {
  const { recipientAddress, amount } = args;
  
  // Validate input parameters
  if (!recipientAddress || !amount) {
    return { error: "Missing required parameters" };
  }
  
  // Convert amount to proper format (assuming NEP-17 with 8 decimals)
  const tokenAmount = parseInt(parseFloat(amount) * 100000000);
  
  // Get the sender address
  const senderAddress = "NhGomBpYnKXArr55nHRQ5rzy79TwKVXZbr"; // Your application's address
  
  // Execute token transfer using Gas Bank for gas fees
  const transferResult = await neo.invokeContract({
    scriptHash: "0x7a16a1f5c40e69790333f3bfe7e4325a08cc2f79", // Example token contract
    operation: "transfer",
    args: [
      senderAddress,
      recipientAddress,
      tokenAmount
    ],
    signers: [
      {
        account: senderAddress,
        scopes: "CalledByEntry"
      }
    ],
    useGasBank: true // This flag enables Gas Bank usage
  });
  
  if (transferResult.error) {
    return { 
      success: false, 
      error: transferResult.error 
    };
  }
  
  return {
    success: true,
    txid: transferResult.txid,
    senderAddress,
    recipientAddress,
    amount,
    gasUsed: transferResult.gasConsumed,
    timestamp: new Date().toISOString()
  };
}

Use Cases

User Onboarding

Remove the friction from user onboarding by sponsoring their initial transactions:

• Allow users to interact with your dApp without first purchasing GAS
• Cover gas fees for creating user wallets or account registrations
• Sponsor a user's first 5-10 transactions to demonstrate value before they commit

Business Operations

Optimize your business operations on Neo N3:

• Manage employee expenses by allocating gas budgets
• Implement departmental gas budgeting and cost tracking
• Simplify accounting with consolidated gas expense reports

DeFi Applications

Enable seamless DeFi experiences:

• Cover gas fees for yield harvesting operations
• Sponsor transactions during high-volume trading periods
• Implement gas rebate programs for loyal users

Example: User-Friendly NFT Minting

This example shows how to create a user-friendly NFT minting experience using Gas Bank:

async function main(args) {
  const { 
    userAddress, 
    nftName, 
    nftDescription, 
    imageUrl 
  } = args;
  
  // Validate user input
  if (!userAddress || !nftName || !imageUrl) {
    return { error: "Missing required parameters" };
  }
  
  // NFT contract script hash
  const nftContractHash = "0x3dfc66447c9280d97b47c2bcf5d625d77f8d2a28";
  
  // Mint the NFT using Gas Bank for gas fees
  const mintResult = await neo.invokeContract({
    scriptHash: nftContractHash,
    operation: "mintNFT",
    args: [
      userAddress,
      nftName,
      nftDescription || "",
      imageUrl
    ],
    signers: [
      {
        account: "NhGomBpYnKXArr55nHRQ5rzy79TwKVXZbr", // Contract admin address
        scopes: "CalledByEntry"
      }
    ],
    useGasBank: true
  });
  
  if (mintResult.error) {
    return { 
      success: false, 
      error: mintResult.error 
    };
  }
  
  // Get the minted token ID from the transaction result
  const tokenId = mintResult.stack[0].value;
  
  return {
    success: true,
    tokenId,
    txid: mintResult.txid,
    nftName,
    nftDescription,
    imageUrl,
    ownerAddress: userAddress,
    gasUsed: mintResult.gasConsumed,
    timestamp: new Date().toISOString()
  };
}

Security and Limits

The Gas Bank Service includes several security features and limitations:

• Transaction Simulation: Transactions are simulated before execution to prevent wasted gas
• Spending Limits: Configurable daily, weekly, and monthly spending caps
• Allowlist Contracts: Restrict gas usage to specific contract script hashes
• Operation Restrictions: Limit which types of operations can use your gas
• Alert Thresholds: Receive notifications when usage hits defined thresholds
• Multi-signature Controls: Require multiple approvals for large gas withdrawals

Best Practices

1. Start with strict gas policies and gradually relax them as you gain confidence
2. Monitor your gas usage patterns to optimize costs
3. Implement rate limiting for user-triggered gas expenditures
4. Use transaction batching for common operations
5. Set up alerts for unusual gas consumption patterns
6. Regularly audit your gas usage to identify optimization opportunities
7. Keep a reserve balance to prevent service interruptions

Integration Examples

Gas Bank with Automation Service

The Gas Bank integrates seamlessly with the Automation Service to ensure automated tasks always have sufficient gas:

// Automation task configuration with Gas Bank
{
  "name": "Daily Token Distribution",
  "description": "Distribute tokens to stakers every day",
  "trigger": {
    "type": "schedule",
    "schedule": "0 0 * * *"  // Daily at midnight
  },
  "action": {
    "type": "contract",
    "scriptHash": "0x7a16a1f5c40e69790333f3bfe7e4325a08cc2f79",
    "operation": "distributeRewards",
    "args": []
  },
  "gasConfig": {
    "useGasBank": true,
    "maxGasLimit": 50,
    "gasPrice": 1000,
    "budgetCategory": "Staking Rewards"
  }
}

API Reference

For a complete API reference, see the Gas Bank API documentation.

Next Steps

• Gas Bank Integration Guide
• Automation Service Documentation
• Functions Service Documentation
• Gas Bank API Reference