Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.lucid.foundation/llms.txt

Use this file to discover all available pages before exploring further.

The gas_utils program handles LUCID token collection for gas fees. It burns a configurable portion of tokens and distributes the remainder to specified recipients on-chain. Program ID (devnet): EzuUhxtNAz1eRfAPypm6eAepe8fRQBrBPSo4Qcp1w3hm

​
Instructions

InstructionDescription
collect_and_splitCollect gas tokens: burn a portion and distribute the rest
mint_and_distributeMint and distribute tokens (not yet implemented)

​
collect_and_split

The primary instruction. Takes iGas (per-inference) and mGas (per-epoch-root) amounts, burns a percentage, and distributes the remainder to recipients proportionally.

​
Parameters

ParameterTypeDescription
m_gas_amountu64mGas tokens (epoch root commitment fee)
i_gas_amountu64iGas tokens (per-inference fee)
recipientsVec<RecipientShare>Recipients with percentage shares
burn_bpsu16Burn percentage in basis points (0-10000)

​
RecipientShare

FieldTypeDescription
recipientPubkeyRecipient’s public key
percentageu8Share of distributed amount (0-100)
Percentages across all recipients must sum to exactly 100. Maximum 10 recipients.

​
How It Works

  1. Total gas = m_gas_amount + i_gas_amount
  2. Burn amount = total_gas * burn_bps / 10000
  3. Distribution amount = total_gas - burn_amount
  4. Each recipient gets distribution_amount * percentage / 100
  5. Burns are executed via CPI to the SPL Token Burn instruction
  6. Distributions are executed via CPI to the SPL Token Transfer instruction

​
Accounts

AccountDescription
user_ataUser’s LUCID token account (source of funds)
lucid_mintLUCID token mint (required for burn)
userSigner paying gas
token_programSPL Token program
remaining_accountsOne TokenAccount per recipient (same order as recipients)

​
Validation

  • Recipient token accounts are validated against declared recipient pubkeys
  • Recipient token accounts must use the same LUCID mint
  • User ATA mint must match the provided LUCID mint

​
Gas Fee Schedule

Fee TypeAmountTrigger
iGas1 LUCIDPer inference call
mGas5 LUCIDPer epoch root commitment
Batch7 LUCID totalBatch commit (2 base + 5 mGas)

​
Events

EventFields
GasCollecteduser, m_gas_amount, i_gas_amount, total_amount, burn_amount, distribute_amount, burn_bps, recipients

​
Errors

ErrorDescription
TooManyRecipientsMore than 10 recipients
NoRecipientsEmpty recipients list
InvalidPercentageSumPercentages do not sum to 100
ZeroGasAmountTotal gas is zero
InvalidBurnBpsburn_bps exceeds 10000
MintMismatchUser ATA mint does not match LUCID mint
RecipientAccountMismatchremaining_accounts count differs from recipients
RecipientOwnerMismatchRecipient ATA owner does not match declared recipient
RecipientMintMismatchRecipient ATA mint does not match LUCID mint