Gasless Execution & Citadel Facilitator

Overview

Traditional blockchain agents require users to maintain native gas balances on every chain. This creates a compounding UX problem: a user running agents on Base + 0G + Solana must separately acquire and manage ETH, A0GI, and SOL — before a single useful action can occur.

Opacus solves this at the infrastructure level with the Citadel Facilitator: a set of platform-owned gas wallets that monitor every execution and top up any wallet that would otherwise fail due to insufficient native gas.

How it works

1. User deposits USDC into their Kinetic Ledger balance (on-chain, Base USDC).
2. User creates an agent or triggers any on-chain operation (bridge, swap, storage, compute).
3. Before submitting the transaction, Agent Kernel calls GasStationService.ensureGas(chain, walletAddress).
4. The gas station checks the execution wallet's native balance against a threshold (default: 0.00005 ETH equivalent).
5. If the balance is below the threshold, the facilitator sends a top-up (default: 0.0007 ETH / 0.0007 A0GI / 10,000 lamports) to the execution wallet.
6. The original transaction proceeds without delay.
7. A 1% platform fee is deducted off-chain from the user's Kinetic Ledger via ledger.debit(). No on-chain fee transaction is needed.

Supported chains

Platform fee structure

All fees are deducted off-chain from the user's Kinetic Ledger balance. There is no on-chain fee transaction, and therefore no gas cost for the fee itself.

The 1% rate is configurable via OPACUS_PLATFORM_FEE_BPS (100 = 1%). Fees are credited to the treasury address (OPACUS_FEE_RECIPIENT).

Architecture

The facilitator is implemented in agent-kernel/src/gasless/gas-station.service.ts as GasStationService. It is instantiated at server startup and injected into all execution paths.

// Execution flow (simplified)
async executeOperation(chain, walletAddress, operationFn) {
  // 1. Ensure native gas is present
  await gasStation.ensureGas(chain, walletAddress);

  // 2. Execute the on-chain operation
  const result = await operationFn();

  // 3. Deduct platform fee from Kinetic Ledger (off-chain)
  await chargePlatformFee(userRecord, operationAmount, 'bridge');

  return result;
}

GasStationService API

REST endpoint — GET /api/gasless/status

Returns the current state of the gasless system, including facilitator wallet addresses and balances.

curl -H "x-opacus-user-email: you@example.com" \
     http://localhost:3006/api/gasless/status

Response:

{
  "ok": true,
  "gaslessEnabled": true,
  "platformFeeBps": 100,
  "platformFeePercent": 1,
  "facilitatorAddresses": {
    "base":   "0x5e610033a5AA7DF74f469917A1746d929Daa784b",
    "og":     "0x39fADDd6189042BEa44FD290D0a8d488146e2aCF",
    "solana": "G1eDkth1i5oR4ZNSGWevz95WmU9zHed8A43ZtY4WDYyR"
  },
  "facilitatorBalances": {
    "base_eth":    "0.00025 ETH (0x5e610033…)",
    "og_native":   "1.0 0G (0x39fADDd6…)",
    "solana_sol":  "0.006402 SOL (G1eDkth1…)"
  },
  "note": "Fund each facilitator wallet with native gas token. Users only need USDC in their Kinetic Ledger."
}

Environment variables

Funding the facilitator wallets

After setting the private keys and restarting with pm2 restart opacus-kernel --update-env, retrieve the generated wallet addresses:

curl -H "x-opacus-user-email: admin@opacus.local" \
     http://localhost:3006/api/gasless/status | python3 -m json.tool

Fund each address with the recommended amount before going live:

Security considerations

• Facilitator private keys should be stored only in .env.local (excluded from git). Never commit them.
• These wallets hold only small gas amounts and have no access to user funds.
• The top-up amount per transaction is small by design (~$1.80 ETH equivalent per Base top-up) to limit exposure if a key is compromised.
• Rotate keys immediately if compromised: generate new wallets, update env vars, restart with --update-env.

Full fee flow diagram

User action (e.g. bridge 100 USDC Base → 0G)
        │
        ▼
GasStationService.ensureGas("base", executionWallet)
  ├── check ETH balance on Base RPC
  ├── balance < 0.00005 ETH?  YES → send 0.0007 ETH from facilitator
  └── balance OK → skip (no cost)
        │
        ▼
Submit bridge transaction (execution wallet now has gas)
        │
        ▼
chargePlatformFee(user, 100 USDC, "bridge")
  ├── fee = 100 × 1% = 1.00 USDC
  ├── ledger.debit(1.00 USDC, { source: "manual-adjustment", note: "platform-fee:bridge" })
  └── record in db.payments for audit trail
        │
        ▼
Return: { txHash: "0x…", platformFee: { method: "kinetic-ledger", charged: true, amountUsdc: "1.00" } }